Advant® OCS 


AdvaSoft for Windows 


User’s Guide 


Advalnform User API 
Advalnform DDE Server 
System Status 

System Messages 


Use of DANGER, WARNING, CAUTION, and NOTE 


This publication includes DANGER, WARNING, CAUTION, and NOTE information where appropriate to point out safety 
related or other important information. 


DANGER Hazards which could result in severe personal injury or death 
WARNING Hazards which could result in personal injury 

CAUTION Hazards which could result in equipment or property damage 
NOTE Alerts user to pertinent facts and conditions 


Although DANGER and WARNING hazards are related to personal injury, and CAUTION hazards are associated with 
equipment or property damage, it should be understood that operation of damaged equipment could, under certain operational 
conditions, result in degraded process performance leading to personal injury or death. Therefore, comply fully with all 
DANGER, WARNING, and CAUTION notices. 


TRADEMARKS 
Advant, AdvaCommand, Advalnform, and AdvaBuild are registered trademarks of ABB Asea Brown Boveri Ltd., Switzerland. 
AdvaSoft is a trademark of ABB, Asea Brown Boveri Ltd., Switzerland. 
SQL* Net is a registered trademark of Oracle Corporation. 
Microsoft, MS, and MS-DOS are registered trademarks and Windows is a trademark of Microsoft Corporation. 


Intellution and SPECIFIX are registered trademarks, and THE FIX, FIX MMI, FIX DMACS, FIX BOS, FIXation, and Click 
and Slick are trademarks of Intellution Inc. 


All other brand or product names are trademarks or registered trademarks of their respective companies or organizations. 


NOTICE 


The information in this document is subject to change without notice and should not be construed as a commitment by ABB 
Industrial Systems AB. ABB Industrial Systems AB assumes no responsibility for any errors that may appear in this document. 


In no event shall ABB Industrial Systems AB be liable for direct, indirect, special, incidental or consequential damages of any 
nature or kind arising from the use of this document, nor shall ABB Industrial Systems AB be liable for incidental or 
consequential damages arising from use of any software or hardware described in this document. 


This document and parts thereof must not be reproduced or copied without ABB Industrial Systems AB’s written permission, 
and the contents thereof must not be imparted to a third party nor be used for any unauthorized purpose. 


The software described in this document is furnished under a license and may be used, copied, or disclosed only in accordance 
with the terms of such license. 


CE MARKING 
This product meets the requirements specified in EMC Directive 89/336/EEC and in Low Voltage Directive 72/23/EEC. 


Copyright © ABB Industrial Systems AB 1997. 


Template: 3BSE001286/E 


3BSE 006 236R0301 


d/p9¢ LOOASEE 


3BSE 006 236R0301 


1.1 
1:2, 
1.3 
1.4 
1.5 
1.6 
1.7 


1.9 


AdvaSoft™ for Windows User’s Guide 
Table of Contents 


TABLE OF CONTENTS 
Chapter 1 - Introduction 
General Information: .c.¢ <cccaccehcesiedeseeecsevestheceetsehs neste heen 1-1 
Equipment Requiréments::.).2:0:2. 2 Aig Shae tik esc actio edi net ecestaees 1-5 
Manual Organization 00... cesses ceecseeseceseeecesceeeeeeeeeseeeeseseaecaeecaessaeaeseenseentees 1-6 
Conventions: 2824 2h.s he siied ect ieee he cee Se ees ees 1-8 
Related, Documentation: ..... 25s. ccccccsesesses ulin ace ca deste cove lech aneie cence ecceeeus Guectedeeveniee ets 1-9 
Release History seseisersicechs iva ncabiseliitucedeeeeieed aan earkale 1-11 
TOPMIN OOS Ys es sisi. wsadcedies teackistescossasnsteodes tarsus tens suateve senses vacsesecedsieedes anda suaoneattee Souaeaes 1-11 
1.7.1 ADDIeViatlOns soko seca ckcceiiees beessec SB Aseere hh Seseoss nolan ate seeded ees 1-11 
1.7.2 Definition Of Terms .sse...i5.23 secs Siaesesg ne eestiee Hg eecoeeesl Shes weet enceesn detent 1-13 
Product: OVErview <. 202. n cess diac ae ee ead es hd she heen ieeeee dence eto aencdeee bits 1-15 
1.8.1 Basico nitscoc cashes AosieBavecad eee ee asec es 1-16 
1.8.2 AdvalInform for WindOwWS..........:::ccccssscesesceeessecesseceeesneeceesaeecsneeenseeeenaes 1-16 
1.8.2.1 AdvaInform DDE Server ...........::ccceccesssseeeseceeesteeesneeees 1-16 
1.8.2.2 AdvaInform User API .........cccccecsccesscesesecesseceeeseeenneeees 1-16 
1.8.3 AdvaCommand for WindOwS ..........::cccsesseesssecessceeesseeceeeeecsseeensseeeensaes 1-17 
1.8.3.1 AdvaCommand Runtime. ..........c.ccccssccssssecesseceeesteeeeeeeees 1-17 
1.8.3.2 AdvaCommand Development ........... cece eeeeeeeeeeeeees 1-17 
1.8.4 AdvaBuild for Windows .........ccccccccsssscessscesessecesesceeesneecseeeecseeeeesneeeenaes 1-17 
1.8.4.1 AdvaBuild AC 110/70/55........cccescceseeseeceeeecneeeeneeeeeeens 1-17 
1.8.5 Basic: FUnctiOns+s25:-).cs sesh vt esbecen tient eeeense heen eh See 1-18 
1.8.5.1 System: Status:i.ccinh ethene we 1-18 
1.8.5.2 System: MESSAGES. cscs. saceeweseiits eecssheeeces heeetbres covers 1-18 
1.8.5.3 Advant Fieldbus 100 Interface .........0.cccccsesseesteeeeeees 1-18 
1.8.5.4 GCOM Unterface sci ccesets cence: ths he ace aos 1-19 
1.8.5.5 SQL*Net TCP/IP for WindOWS...........::ccccsececesteeesteeeees 1-20 
1.8.6 Support for third-party products ....... eee ee eseesee cee ceseceeceseeeseneeeeenes 1-20 
1.8.6.1 Application and communication software ......... 1-20 
1.8.7 Configuration alternatives... eee eceeeeeceeeeeeeeeeeseecaeesaecaecsseeseenaees 1-20 
User Interfaces <: :eicicce.c cece ences dietnies Hie i ett etn ees 1-22 


Chapter 2 - Installation 


2.1 
2.2 


2.3 


Site-Planning Environment... eee cee eeceeeeeeeeeeseecaeeseecaecseseseeseseseeeeseesaeeaeenaes 2-1 
SOLU escsil es asedoncess cbadighesbesdetaces usta cae HbA stees: Gan csdersense sTavealenaseibeaveeasedsteus shes dbaneadtates 2-1 
2.2.1 Installation procedure-.i..4 siahvdnaii ai hee Gatch aem ease 2-1 
Shutdown: Procedures: ceccs ise eseieeuiin een aelues ieee eee 2-3 
2.3.1 Normal: Shutdowasssisc% sosctehvensececbessotaconehst sae be sbiee otaponscsuabencauatietes seastaaved ahs 2-3 
23:2, Emergency shutdown... ce ceecesceseeceseseeeeseessecseesaecsaseaecscneeerenseeees 2-3 


AdvaSoft™ for Windows User’s Guide 


Table of Contents 


CONTENTS (continued) 


2A. - Start-Up PLOCEAUIES ss. ockesseic iss ves chaes Sone supe Sas ea aoak eaten anda depen ac NEL Seeoeees Lees weed Soeeoeh 2-3 
2:5). ~ PLOCUCt VEREICATIONY Jest ee ieee Aes A eRe Ses eee dees oe 2-4 
Chapter 3 - Configuration/Application Building 
3.1 Design Considerations 0.0.0.0... cee ceceseesceseeeeceeeeeecseeesecaeesaecsecsaecasceseeaeceeseeeeeaeeeesenes 3-1 
3:2, - “Capacity and: Performance sss. ssesetcssessesueconcca bean soapbessovsscaanbanteessu tes Gopeavapoescaugehecarey 3-1 
3.2.1 Primary Memory reqUireMENts....... ee eee eee eeseete cee ceteeeeceeeeeeeeeeeeeeenes 3-6 
3.2.2 Disk: Stora BG: ese2 scarves hecstentlee saber ites dedicate atest 3-6 
3.3° “Application Starteup ss iicc. sscisstesiss stiches joa scdests aeadseseeSocesceses ogee sen tacsaseovdgensasegssdastendesters 3-6 
3.3.1 DDE ‘Servet vcscsssecsSsses cases caste cuseb as ch cosas ites ieeses cacboesctcsstantesnessceess cvsesianeecess 3-6 
3.4 Tutorial using AdvaInform DDE Servet... eee ceesseceeceseceeceseeeeceeeeeeeeeeenesenes 3-7 
3.4.1 Application building example with MS-Excel....... eee eee eee eneeeee 3-7 
3.4.1.1 Defining the protocol alias oe eee eeseeseceseeteeneeees 3-7 
3.4.1.2 Cyclic Request for process data 0... eee eeseseeseeeeeeeeees 3-7 
3.4.1.3 Demand request for process data... cee eeeeeeseeeeeeeeees 3-9 
3.4.1.4 Sending commands... eee ceeeeeceeeeeeeeeeeseeeaeeeeeaees 3-10 
3:35 « Application Procedures’... acc. essstese:cssestesuechccesaeupcosocdeosstnsgnsnventees shee atée sasenessceongavast 3-11 
3.5.1 Defining a protocol alias... eee cee ceeceseeesceeeeeeceeeeeeeeeeeseeeaeesaeeaee 3-11 
3.5.2 Configuring the DDE Servet... ce ceseeceeeeeeceeeeeeeeeesseeeneeeeeaee 3-12 
3.5.3 Advalntorm: User ARI i... esdeseivcriui tence 3-13 
3.6 Configuration/Application Building Menus ...0..... cece cee eeeceeessececeseeeeeseens 3-13 
3.6.1 Pile IMO. 5254 soctoseatioes cagecheoes oe bepivatengscdaetines saeass Macensartaocteeass oetengereetes 3-13 
3.6.2 Options menu: ei te i Rihana 3-14 
3.6.3 HIE Pp MOM ss rsesseareds esh ces sp scvsh desea dig ecog a vente teettheoeneoitorr ass ate sheesteeeees 3-15 
3.6.4 DDE SQrven cesses ices ses sects decd, Siac cos sg ste vp bdon sis tosestestectacess a biacassostataeteaaeae 3-16 
3.6.4.1 Pale Men ou. 55 ssciencesasehtaceecssstel one cestecsceees suite lberscostermeeees 3-16 
3.6.4.2 COnP Sure MENU, .:.2isescck esc a eta ead ie eeon, ees 3-16 
3.6.4.3 Help ménuhn eke nde ee 3-17 
3.7  “NetD DES. fsciis cons iieideeects Gelioheiciedouttent neltheetadn eae is oe eed cise 3-18 
3.7.1 Configuring NetDDE Server Support ......... cece eee eceeeeeeeeeeseeeeeneeenees 3-18 
3.7.2 AdvalInform DDE Server NetDDE Addresses... eee eeeeseeeeeeee eres 3-19 
Chapter 4 - Runtime Operation 
AY —Product-Operation.:c....<cccscccecdscvssccvcssanesechuctunss sauceuhssedae sovesvbesatesctebae ctedscbasevcedvastectss 4-1 
4.2. - ‘Operating OVERVISW es. sss. sosdesies.scgs tee ives sat. baiestesesbdocsdosspeosasdeceates.seibeaseesgedsteetsoubes® 4-1 
4.2.1 Basic Umitiesce eben wees eet eech 8 ae es ea see ee eats Glos Ge 4-2 
4.2.2 OPULONS 253 0 Sees BOG Sachs Gusto te teres leah esse rete eviews 4-2 
4.2.2.1 AdvaCommand Runtime... cece cseceseeseceeeseeeeeees 4-2 
4.3. Runtime Tutorial o..cssc.ccsccscccscvesecxcssahesecusteunesscuuteutesesseceevdeecesdes sctbnaestesstevascveeermesectes 4-2 


3BSE 006 236R0301 


3BSE 006 236R0301 


AdvaSoft™ for Windows User’s Guide 
Table of Contents 


CONTENTS (continued) 


44. “Operating Instructions. siesssctsee.seensisee. oul teeta ae in en eee See ee en eke 4-2 
4.4.1 Viewing the System Status oc. cess cseeseecsecsseesecsseeeceseeseeeeeeseeees 4-3 

4.4.2 Reset Diagnostics... eceececessceeceeeeeeeeseeeseeseecaecsacesecsacesecseeseeeeeeseeees 4-3 

4:5. Runtime Operation. Menus i: :.cscs ss sescectsisssstavessosepescestegaasesvadegossesntetectsesvesssesvaoetstys 4-4 
4.5.1 Pulé: Menen awe et aie edhe hed a eae a hn ei: 4-4 

4.5.2 OPtONs MENU ss 3013 eas cect sien ates cl ess OU eaten oS eiieaeeee es 4-4 

4.5.3 PIS] p Men sesssivetessetheces Soechaites saeethavsthcousneeieeeshiaa pa on cruaoen ouside ase aes 4-5 

4.5.4 System Messages ......... ce ceceeeeeecseeesecseessecsecsecnsceseeeceeeesseeeesaseaevsaesaeenaes 4-5 
4.5.4.1 Ul: Mn, fesse) sseael esSroscescssesertesciee eeepc ee by esas 4-5 

4.5.4.2 Oputons Menu). 3 aos cicinaieidkeeie ene el aiee 4-5 

4.5.4.3 Ble lp Menu sis. seis cseciecess diskesscucsetnesececeenaesscasseuacuscuevecsceeenees 4-6 


Chapter 5 - Maintenance 


5.1 ‘Preventive. Maintenances. ..2./2.scissesstsccsisseshsessssseseoss aeeeace. cosdeargeegedsteetsovsessecsnooveatey 5-1 
3.2" Hardware Indicators ..4 isa adie tek ei Sa ena ehh een dias 5-1 
D3. . SYSTEM MESSAPeS saci tesco ives seele eeeeuchate este snt tu detent wa sleds Sil eugene Hen Sead eee 5-1 
5.4 Fault-Finding and User Repair oo... eee cceeeeecseeseeceeessecseceaeeaeceseeseceseseseeeeeeees 5-2 
5.4.1 Troubleshooting 0.0... eeeccecesecesceseeeeceseeseeeseeeaecaesaeeeeseeeseaseaetaeeeaeesaes 5-2 

5.4.1.1 Help menus for application building... ee 5-2 

5.4.1.2 System: Status sieves evisu aendsdenie eee cies 5-2 

5.4.1.3 System Messages 0.0... ceeccsessecsecsseeseceseeseceseeseeeeeeeeeees 5-2 

5.4.2 How to get support from ABB... eee eseeceecneeeseceeeaececeseeesenseeees 5-2 


Appendix A - References 
AA RTO SPM Msc asa a ler i CE A-1 


Appendix B - References 


B.1 = Advalnform User API... eecceeccessecencecescesnceeseeesaeceacecseecsaesencesseeeeaeceseeseesaeeeeeeeeeees 3 
B.1.1 AdVaSOreeXtENSlONS ws. isevsedvestdeatecsaeeesecdes cestredtew sessed eden aya etieente 3 
B.1.1.1 Init communication handlers .......... ce ceeeceesceeeeceeeecsseceeeeesees 4 

B.1.1.2 Configure communication handlet........... eee eect eeeeees 5 

B.1.1.3 Resolve Symbols. 20..3.csscssic) sessesssss noes oss. b ate eaaactnG Seana 6 

B.1.1.4 Display Communication Status... eee eseceeeceeeeeees 7 

B.1.1.5 Réset Dia@nostis:.., ss. eve vecspetiestcsteeepensecrbrestetesaeetee es 8 

B.1.1.6 Terminate communication handlers «0.0.0.0... ceeeeeseeeeseceeeeees 9 

B.1.1.7 Allocate MOMOTY 00... eee eee ceeesee cae ceeeceeeeseeeceseeeeeneeeees 10 

B.1.1.8 RES MOMOLY: Secchi ccsiecees cette veciteees Seite teeeoas ston coSnaeh snneecneenes 11 

B.1.1.9 Reallocate MEMOTY 0.0... eee ee esee ce ceeeceeceseeeceseeereneeeees 12 


AdvaSoft™ for Windows User’s Guide 
Table of Contents 


CONTENTS (continued) 
B.1.2 Basic Supports: ts cesGucseaneseees eveeeul ssaeteta he epee edie eho gee eet 13 
B.1.2.1 Get System: Time vvowasih Meath ee Aad, 13 
B.1.2.2 Get Local Times. ciccsccciccosscsstecestensecs actesns cee cecss eeensesenevevtces 14 
B.1.2.3 Get Standard Tim 62 siissc.ssecescecpsacestsviscsessstdsgcasssvtettotsesingare 15 
B.1.2.4 Send Message*.s adie sth vila Ae aes eta 16 
B.1.2.5 Get Local Node: aisiedesicnih ates eas ThG wae iewertecet 18 
B.1.3 Object ACCESS: SeLVICES iss ci .ch os fshsies seestdash sth conenesstebe shies edepcpyesussmcageaetaa aes 19 
B.1.3.1 Get Object Type... eee esecsecseessecssessecseceseeseeeesreneeeees 20 
B.1.3.2 Get Object Type Attributes... cece ceseeereeeeeees 22 
B.1.3.3 Get Attribute Values One... eeeceeeeesseceneeceeeeenseeeeeeeeees 24 
B.1.3.4 Get Attribute Values on Event.........ccceeceseecereeeeteeeeeeeeees 27 
B.1.3.5 Get Attribute Values Cyclically oo... eeeeeeeeeeeeeeees 32 
B.1.3.6 Get Attribute Values on Event with Init... eee 37 
B.1.3.7 Can CelKG etre eaicuscdetectser eet tase enniiend bites hee hess 40 
B.1.3.8 Cancel All Subscriptions 000.0... eee ceeceseeseceseeereeeeeees 42 
B.1.3.9 Execute Operation 0.0... eee cseseceeeeseceeceseeseeeseeeseneeeaes 43 


INDEX 


iv 3BSE 006 236R0301 


AdvaSoft’’ for Windows User’s Guide 
Section 1.1 General Information 


Chapter 1 Introduction 


1.1 General Information 


This guide describes AdvaSoft for Windows, the Advant OCS platform software product for 
applications using IBM-compatible personal computers with Microsoft Windows. The primary 
uses for AdvaSoft for Windows are as follows: 


° To provide an entry level, PC-based operator station. 


° To act as an information server for PC networks. This uses the DDE Server capabilities to 
provide access to the automation system real-time process databases from Windows 
applications. 


° To provide a user application programming interface giving software developers easy 
access to the distributed databases in the Advant OCS. 


° To provide functionality for Advant Controller 110/70/55 application programming. 


° To provide a graphical, SQL user interface for Advant Station 500 Information 
Management Stations. 


AdvaSoft for Windows includes AdvaInform for Windows (information management) 
functionality, AdvaCommand for Windows (operator interactive) functionality, AdvaBuild for 
Windows (engineering functions) and basic functions. AdvaSoft for Windows is packaged as a 
basic unit with options available separately. 


AdvaSoft for Windows 
AdvaCommand Advalnform AdvaBuild 
- AdvaCommand - Advalnform - AdvaBuild 
Development DDE Server AC110/70/55 
o - AdvaCommand 
3 Runtime 
1S - FIX Database* 
= 
= Advalnform 1S 
3 User API 5 
2 |__ AdvaSoft basic functions x) 
: 2 
System Messages System Status te 


GCOM 
Interface 


SQL*Net 
for TCP/IP 


AF 100 
Interface 


* Both versions of AdvaCommand, Development and Runtime, are available with the FIX 
Database option 


Figure 1-1. AdvaSoft for Windows 
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This guide is designed to assist users of AdvaSoft for Windows and to provide product 
orientation. It contains information about installation of all available options, as well as 
application building, operation and maintenance of the functions included in the basic unit. 
You should be familiar with Microsoft Windows 3.1 or later to use the software described in this 
guide. 


The functions included in the basic unit make AdvaSoft for Windows applications independent 
of the underlying communication architecture. The following functions are included: 


° AdvalInform User API 
° System Messages 


° System Status 


Application building capability and runtime operation for information management are 
provided by functions in the AdvaInform for Windows family: 


° The AdvalInform DDE Server makes it possible for client third-party applications 
(for example, Microsoft Excel) supporting DDE to exchange data with the distributed 
real-time database in the Advant OCS. 


° AdvaInform User API, a third-generation programming (3-GL) interface for building your 
own applications, provides application portability between different information 
management products. 


NOTE 


Note that neither AdvaInform DDE Server, nor the AdvaInform User API, can 
access data via SQL*Net TCP/IP for Windows. 


Application building capability and runtime operation for operator control are provided by 
functions in the AdvaCommand for Windows family: 


° With AdvaCommand Runtime, you can use picture files and a number of predefined 
displays created with AdvaCommand Development. Functions for multiple security levels, 
historical trending and process data presentation are included. Tools for creating and 
generation of reports, by using predefined macros, are also included. 


AdvaCommand Runtime, in conjunction with the SQL*Net TCP/IP for Windows, 
provides access to Advant OCS real-time and historical data through SQL over a TCP/IP 
network. 


° AdvaCommand Development provides the same functionality as AdvaCommand Runtime, 
plus graphical, text, data and animation tools that let you create high-resolution, real-time 
operator displays. 
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Application programming capability and configuration, together with engineering support, are 
provided by the AdvaBuild for Windows family: 


AdvaBuild provides application programming and configuration towards Advant 
Fieldbus 100 and AC 110/70/55 and AdvaSoft for Windows stations. The direct 
connection via AF100 is only supported if the AF100 option is included in Advasoft for 
Windows. 


AdvaBuild provides consistent and ergonomic presentation of all tools, which reduces 
training needs and promotes natural learning. 


The AdvaBuild AC 110/70/55 option includes: 
— Application Builder 
— Function Chart Builder 


— Bus Configuration Builder. 


AdvaSoft Basic Functions provide common resources used by one or more options and 
communication for access to third-party and proprietary ABB networks: 


The System Messages option collects error messages from installed AdvaSoft software. 
The System Status reports communication status from the different networks. 


The Advant Fieldbus 100 Interface enables communication with the fieldbus network and 
includes both software and hardware (communication board). 


The GCOM Interface enables communication with the GCOM network and includes all 
necessary software. 


Further flexibility and openness are offered for third-party applications using SQL*Net 
TCP/IP for Windows. It is also possible to combine with third-party software products, for 
example, X-terminal software. 
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Refer to Section 1.8, Product Overview for more detailed information and typical 


configuration examples. 
Advant Station 500 IMS 
AdvaSott 
for 
Windows 


| GCOM,|TCP/IP and MasterBus 300 Plant Network 


b 


a 


Advant Station 500 Series IMS 


AdvaSoft MasterGate 230/1 
or 
Windows s ery | 


eb 


JO TT | 
GCOM/MasterBus 300 Canirel Network 


AdvaSoft Advant Controller 


for 400 Series LEE 
Windows . 7 
nterface ! 
| Fieldbus 100 Fieldbus Network 


eo APC 


Advant Controller 
110 Series 


—— 
ee 
— 

ee 


Figure 1-2. AdvaSoft for Windows in an Advant OCS 
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1.2 Equipment Requirements 


Below is an overview of the equipment requirements for AdvaSoft for Windows and its options. 
For more detailed requirements for each application and communication option, refer to the 
corresponding user’s guides. 


Hardware requirements 


Table 1-1. Minimum recommended hardware for AdvaSoft for Windows 


Component AdvaSoft for Windows 
Personal computer (PC) 486DX2/66 MHz 
Primary memory (RAM) 16 MB 
Hard disk drive (with available memory space) 70 MB 
No. of 1.44 MB 3.5" diskette drives 1 
No. of spare standard PC AT slots () ie 


(1) One spare standard PC AT slot for each of the following hardware options where applicable: 
— IEEE 802.3 interface board for TCP/IP 
— Advant Fieldbus 100 Interface board for Advant Fieldbus 100 Interface equipped system. 


Table 1-2. Disk space requirements for AdvaSoft for Windows product installation” 
Unit Disk Space (kB) 
Basic Unit 220 
AdvaCommand Development 28000 
AdvaCommand Runtime 26100 
AdvaBuild AC 110/70/55 11200 
Advalnform DDE Server 140 
GCOM Interface 450 
Advant Fieldbus 100 Interface 630 
SQL*Net TCP/IP 10 000 


(1) Development environment toward User API is not included in the AdvaSoft for Windows product. 


Operating System requirements 
° Microsoft Windows 3.1 or 3.11 
° Microsoft MS-DOS 5.0 or later. 


3BSE 006 236R0301 1-5 


AdvaSoft™ for Windows User’s Guide 


Chapter 1 Introduction 


1.3 Manual Organization 


In this guide, you will find information about what AdvaSoft for Windows comprises, how to 
combine options, and an overview of the functionality of each available unit. For instructions 
about application building, runtime operation and maintenance beyond the parts included in the 
basic unit, refer to corresponding user’s guides. Figure 1-3 below shows what each chapter and 
section in this guide includes. 


Chapter 
Configuration/ Runtime 
Introduction Installation App ane Operation Maintenance | | Appendices Index 

uilding 
Before you Site Planning Design | Product Preventive References 
Begin Environment Considerations Operation Maintenance 
Equipment Setup Capacity & Operating Hardware 
Requirements Performance Overview Indicators 

Shutdown —— 
How to Use Procedures Application Runtime Error 
This Book e Start-up Tutorial Messages 
tart-u 

Conventions Procedures Tutorial Operating Fault Finding, 

ae Instructions & User Repair 
Related Product. Application 
Documentation Verification Procedures Runtime 

; Operation x. 
Release Configuration/ Menus : 
History Application Section 

Building Menus 
Terminology 
Configuration/ 

ae Dialog Boxes 


User Interface 
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Figure 1-3. Structure of this guide 


Chapter 1, Introduction 


This chapter provides an overview of this document and the AdvaSoft for Windows product. 


Chapter 2, Installation 


This chapter briefly explains considerations for site-planning and configuration, depending on 
the units included in your system. For detailed information, refer to the corresponding user’s 
guide. 
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Chapter 3, Configuration/Application Building 


This chapter gives you hints about design considerations for AdvaSoft for Windows, depending 
on your system configuration. It also provides a quick reference for memory and disk space 
requirements for application data, as well as performance information on each software and 
hardware unit available. For detailed information on each unit, refer to the corresponding 
user’s guide. 


Chapter 4, Runtime Operation 


This chapter gives an overview of operation possibilities, depending on the configuration of 
your system. For detailed information on each unit, refer to the corresponding user’s guide. 


Chapter 5, Maintenance 


This chapter describes how and when to report system problems to ABB Industrial Systems. 
It also contains maintenance instructions and error messages for the basic unit. For detailed 
information on each option, refer to the corresponding user’s guide. 
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Conventions help you interpret information easily. This user’s guide employs consistent visual 
formats for ease of recognition. The following conventions are used throughout this guide: 


Examples Convention description 
..AdvaSoft for Windows _|Document names are in italics. 
User’s Guide... 


...Personal Computer 
(PC) 


Names abbreviated are written in full the first time they are 
presented, followed by the abbreviation. 


...press Delete... 


If you are to press a single key, the keys labeled on the 
keyboard are capitalized and are written in Boldface, e.g., 
“... press <Ctrl>...” or “... press the Ctrl key....” Keys not 
labeled on the keyboard are in boldface in lowercase 
letters, e.g., “...press <enter>....” 


...press and release <Alt, 
F4>... 


If you are to press and release more than one key, key 
names are separated by a comma (,). 


...press <Ctrl-S>... 


If you are to press more than one key at a time, the key 
names are separated by a dash (-). 


...press the CANCEL 
button... 


Screen buttons appear in BOLDFACE, in all uppercase 
letters. 


...select the Print item in 
the File menu... 


You are instructed to choose menus and menu items. 
Names of menus and menu items appear in Boldface and 
start with an uppercase letter, e.g., Help menu. 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


Program source text is written in Courier font. 


...you type MYIMS in 
the... 


Characters you are to type appear in boldface. 


...click on the... 


“Click” or “Double-click” means pointing with the mouse 
cursor, then clicking the left button. 


Highlighting part of a text 
or spreadsheet 


Select is used, for example, when you are instructed to 
select cells in a spreadsheet. 


Do the following: 
1. Select... 


Qoec 


When you are asked to perform sequences of operations, 
they are numbered in chronological order. 
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1.5 Related Documentation 


Below is an overview of required, optional and related documentation available from ABB, 
depending on your system configuration, followed by a short description of each guide. 


Communication Application 
related related 
Advant Fieldbus 100 Interface | AdvaCommand Development Database Builder 
AdvaSoftt for Windows AdvaCommand Runtime AdvaCommand for Windows 
User's Guide AdvaCommand for Windows User’s Guide 
User’s Guide 
GCOM Interface ; : 
AdvaSoft for Windows AdvaCommand Development AdvaBuild for Windows 
User's Guide Documentation Binder Application Builder 
Advant Fieldbus 100 AdvaCommand for Windows User's Guide 
User’s Guide User’s Binder 
SQL “Net TCP/IP AdvaCommand Runtime salle rea aie dpa ete 
AavaSoft for Windows Documentation Binder wee are? 
User’s Guide User’s Guide 


3BSE 006 236R0301 


AdvaCommand for Windows 
User’s Binder 


Figure 1-4. AdvaSoft for Windows and Related Documentation Tree 


Advant Fieldbus 100 Interface 
AdvaSoft for Windows 
User’s Guide 


This guide gives you instructions on configuration and using the Advant Fieldbus 100 Interface 
for AdvaSoft for Windows. 


GCOM Interface 
AdvaSoft for Windows 
User’s Guide 


This guide gives you instructions on configuration and using the GCOM Interface for AdvaSoft 
for Windows. 


Advant Fieldbus 100 
AdvaSoft for Windows 
User’s Guide 


This guide describes the Advant Fieldbus 100 network. 


SQL*Net TCP/IP 
AdvaSoft for Windows 
User’s Guide 


This guide describes installation and configuration of the SQL*Net and ODBC to run the 
SQL*Net TCP/IP for Windows option. 
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AdvaCommand Runtime 
AdvaCommand Development 
AdvaCommand for Windows 
User’s Guide 


This guide gives you instructions on how to use AdvaCommand Development and 
AdvaCommand Runtime. It is applicable from the time of installation. 


AdvaCommand Development 
Documentation Binder 
AdvaCommand for Windows 
User’s Binder 


These guides give you instructions on how to use AdvaCommand Development for display 
development. 


AdvaCommand Runtime 
Documentation Binder 
AdvaCommand for Windows 
User’s Binder 


These guides give you instructions on how to use AdvaCommand Runtime and are applicable 
after installation. 


Database Builder 
AdvaCommand for Windows 
User’s Guide 


This guide describes how to design and build a process database with the FIX Database. 


Database Builder 
AdvaCommand for Windows 
Reference Manual 


This guide provides detailed information about each FIX database block. Use it in conjunction 
with the Database Builder User’s Guide. 


AdvaBuild for Windows 
Application Builder 
User’s Guide 


This guide describes Application Builder and Bus Configuration Builder. 


AdvaBuild for Windows 
Function Chart Builder 
User’s Guide 


This guide describes how to configure Advant OCS controllers with AdvaBuild Function Chart 
Builder. 
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1.6 Release History 


AdvaSoft for Windows, as well as each available unit or option, has its own release history. 
Refer to the corresponding user’s guides. The version number indicates a major release with 
new functionality, whereas the revision number indicates updates including minor changes or 
fault rectification. 


Table 1-3. AdvaSoft for Windows Product Release History 


Unit Version! Description 
Revision 
AdvaSoft 1.0 Initial version 
Support for AF100, 
SQL*Net and DDE 
Server 
FIX version 5.0 
AdvaSoft 1.1 Extended with the 
AdvaBuild option 
AdvaSoft 1.2 Extended with the GCOM 
communication option 
FIX version 5.5 
AdvaSoft 1.3 AF100 support for 
extended DB elements 
FIX version 5.6 
1.7 Terminology 
1.7.1 Abbreviations 
3-GL 
3-GL stands for third-generation programming language, for example, Pascal. 
AC 


AC stands for Advant Controller, the common name for the Advant Controller series of 
controllers used in Advant OCS, for example, AC 110 and AC 410. 


AF 100 
AF 100 stands for Advant Fieldbus 100. 


APC 
APC stands for Application Performance Controller. An APC is a control unit used to control 
motor drives, etc. 


AS 

AS stands for Advant Station, the common term for the Advant Station series of operator, 
engineering and information management stations within Advant OCS, for 

example, AS 100 Series IMS. 
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DCN 
DCN stands for Distributed Communication Network. DCN is a network option within the 
Advant OCS concept. 


DCS 
DCS stands for Distributed Control System. DCS is a process station with a distributed 
database, for example, Advant Controller 410. This is a common term for such systems. 


DDE 

DDE stands for Dynamic Data Exchange. DDE is a form of interprocess communication that 
uses shared memory to exchange data between applications in the MS-Windows environment, 
as in DDE Server. 


DS 
DS stands for Data Set, an object type in the Advant OCS. 


ES 
ES stands for Engineering Station, a common term for stations with functionality for 
programming and configuring controllers in the Advant OCS, i.e., AS 500 Series ES. 


FTP 
FTP stands for File Transfer Protocol, which provides file transfer functionality on 
a TCP/IP network. 


GCOM 

GCOM stands for Gateway COMmunication. 

GUI 

GUI stands for Graphical User Interface. 

IMS 

IMS stands for Advant Station 500 Series Information Management Station. 

MB 

MB stands for megabytes, as in “...10 MB of disk space....” 

MMI 

MMI stands for Man Machine Interface, a common term for operator interactive functionality. 
MP 200/1 

MP 200/1 stands for MasterPiece 200/1, a series of process stations in the Advant OCS. 
MS 


MS stands for Microsoft Corporation. All Microsoft programs mentioned are preceded by 
“MS,” as in MS-Word. 


MV 800/1 
MV 800/1 stands for MasterView 800/1, a series of operator stations in Advant OCS, with 
releases beginning in 1991. 


NDIS 
NDIS stands for Network Driver Interface Specification, a software option for 
IEEE 802.3 interface. 


OAS 
OAS stands for Object Access Services, a part of the User API. 
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Ocs 
OCS stands for Open Control System. 


ODBC 
ODBC stands for Open DataBase Connectivity, an interface providing a vendor neutral access 
to various database systems. 


OS 
OS stands for Operator Station, a station with operator interactive functionality. 


SQL 
SQL stands for Structured Query Language, a standardized language for query of relational 
databases. 


TCP/IP 
TCP/IP stands for Transmission Control Protocol/Internet Protocol, a standard 
communication protocol. 


TTD 
TTD stands for Time Tagged Data. 


1.7.2 Definition of Terms 


Advant OCS 
Advant OCS refers to one or more of the distributed control systems from ABB Industrial 
Systems, i.e., Advant OCS and ABB MOD 300. 


Client A pplication 

A client application is an application which subscribes to objects from the automation system. 
For example, an application that subscribes to objects via the DDE Server is a DDE client. 
Cyclic 

When a task is executed or a value is updated within certain time intervals, it is cyclic, 

for example, cyclic update of an analog input, with a cycle time of | s. 


DAT Based Objects 

These objects are supported in all versions of AdvaSoft. They offer, compared with the 
Extended DB Elements, limited object support. DAT Based Objects are AI, AO, DI, DO and 
DAT. These objects use COIL files for configuration. 


Demand (request for data) 
When a task is executed or a value is updated on demand from another task, for example, when 
an analog input is updated on demand, it is updated in the requesting node when it asks for data. 


Event 
When a value or object is updated or the status is changed, it is event-updated. 


Extended DB Elements 

These objects offer complete support for the different object attributes. Extended DB Elements 
are AIS, AOS, DIS, DOS. These objects use BOIL files for configuration. 

Item 

An item is a variable used to specify objects including attributes of a communication protocol in 
the DDE Server used by client applications to specify subscription. 
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MasterNet 
MasterNet is the common name of the Advant OCS Computer Network Communication 
System. 


Node 

A node is a network unit with its own address, communicating on a network. A node can be an 
AdvaSoft for Windows, a gateway or an Advant Controller. It is sometimes also referred to as a 
station. 


Object (Process) 

Object (Process) is a physical or calculated process object, or a functional unit or type circuit 
containing all related inputs and outputs. An example of a process object is an analog input 
including value, limits, status, etc. There are two kinds of objects, Extended DB Elements and 
DAT Based Objects. 


Subscription 
A subscription requests data from an automation system. 


System 

System means part or all of an automation system, usually appearing here in the context 
“...units included in your system,” where “system” means AdvaSoft for Windows with options. 
Topic 

A topic is a variable used to specify the name of a communication protocol in the DDE Server 
used by client applications to specify subscription. 

Unit 

A unit pertains to a software or hardware task or part which runs independently or as part of a 
larger unit. The basic unit and Advant Fieldbus 100 are units. 


User Interface 
The user interface is the dialogue between the user and a computer program, as in MS-Windows 
user interface, with program groups, icons, menus and menu items. 
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1.8 Product Overview 


Figure 1-5 below shows a block diagram of the software and hardware units comprising the 
AdvaSoft for Windows product, and other third-party products it supports, followed by a 
summary of each function. 


The general rule for functions included in the AdvaSoft for Windows product is that application 
software, such as AdvaCommand for Windows, AdvaInform for Windows, AdvaBuild for 
Windows or a third-party application interface to communication, must link via functions 
provided in the basic unit or AdvaInform DDE Server. 


AdvaCommand for Windows provides operator interactive functionality and AdvaInform for 
Windows information management functionality. The basic functions include common error 
and system messaging as well as communication to Advant Fieldbus 100 and SQL*Net. 


Third-party application software and communication hardware such as the IEEE 802.3 
(Ethernet) communication board are standard and available through third-party vendors. 


Third-party || 
Applications ird- 
PP «EI pany. X Windows 
Windows applications 
AdvaSoft for Windows 
ABB AdvaCommand Advainform AdvaBuild 
Applications - AdvaCommand - Advalnform - AdvaBuild 
Development DDE Server AC 110/70/55 
- AdvaCommand 
Runtime 
- FIX Database 
Advalnform a 
Basic Unit User API 5 
—  AdvaSoft basic functions ° 
2) 
System Messages System Status a 
AF 100 GCOM SQL*Net 
Interface Interface for TCP/IP 


Communication 


AF 100 
Interface Board 


TCP/IP 


IEEE 802.3 communication board 


3BSE 006 236R0301 


Figure 1-5. AdvaSoft for Windows product overview 


AdvaSoft™ for Windows User’s Guide 


Chapter 1 Introduction 


1.8.1 Basic Unit 


The functions included in the basic unit are partially common to any option you may have for 
the AdvaSoft for Windows product, such as the System Messages option. Additionally, the 
AdvaInform User API offers functionality to make applications independent of underlying 
communication architecture and enables you to build your own applications in a 
C-programming environment. Each of the functions is summarized below. 


1.8.2 Advalnform for Windows 


1.8.2.1 Advalnform DDE Server 


The AdvalInform DDE Server enables interactive exchange of data between application software 
supporting DDE under MS-Windows and the Advant OCS. Microsoft Excel is an example of 
this type of application software. 


Table 1-4 below shows which general services are supported for the various object types. 
You can only use these services if the communication option supports them. See the appropriate 
user’s guide for the communication option used. 


Table 1-4. AdvaInform DDE Server services 


Object type Demand Cyclic Event Command 
Al yes yes no yes 
AO yes yes no yes 
DI yes yes no yes 
DO yes yes no yes 
DAT yes yes no yes 


1.8.2.2 Advalnform User API 


The AdvaInform User API for Windows is a subset of the AdvaInform User API 
(for AS 500 IMS). It provides application portability between various information management 
products and system generations. 


The AdvaInform User API provides the tools necessary to integrate different software 
applications. It gives the application programmer a well-defined environment for software 
development as well as a portable application. 

Implemented as a dynamic link library (DLL), the AdvaInform User API consists of two main 

functional parts which make it possible to build applications and distribute data. 

° Object Access Services provides direct interaction with process and system objects. It is a 
3-GL programming interface to objects within the system. Object Access Services 
supports commands to execute operations on objects and subscriptions for data from 
objects, cyclically, on event or on demand. 

° Basic Support is the 3-GL programming interface to the system. It covers system 
messages and date and time functionality. 

Note that you need a C development environment supporting Windows programs for application 

development with AdvaInform User API. 
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1.8.3 AdvaCommand for Windows 


To meet the different needs of engineering and runtime, AdvaCommand for Windows is 
available in four versions. Their differences are explained below. 


1.8.3.1 AdvaCommand Runtime 


AdvaCommand Runtime uses the displays developed with AdvaCommand Development. It is 
sufficient for any station used for real-time operator functionality. It includes functionality 
which provides the operator with point-and-click style process control capabilities, presentation 
of process displays, reports, and events and alarms, as well as trends and historical data. 


The Runtime version is available in two versions, one with and one without the FIX database . 


1.8.3.2 AdvaCommand Development 


AdvaCommand Development has the full runtime capabilities of AdvaCommand Runtime. It 
also has additional functionality that provides the display designer with the tools to create 
and/or modify the AdvaCommand standard displays and display elements. 


The Development version is available in two versions, one with and one without the FIX 
database. 


1.8.4 AdvaBuild for Windows 


1.8.4.1. AdvaBuild AC 110/70/55 


AdvaBuild for Windows is the engineering tool for the Advant OCS system running under 
Microsoft Windows. AdvaBuild for Windows covers all the features needed for configuring and 
programming the AC 110/70/55 and Advasoft for Windows stations throughout all phases, from 
project start-up to commissioning, maintenance and upgrading, whenever necessary. It is 
backward compatible with projects done with its predecessor, Master Aid 220 Software. 
AdvaBuild for Windows consists of: 


° AdvaBuild Application Builder 
° AdvaBuild Function Chart Builder 
° AdvaBuild Bus Configuration Builder 


You need AdvaBuild for Windows AC 110/70/55 software to configure and program Advant 
Controller 110, Advant Controller 55 and Advasoft for Windows stations. 


AdvaBuild for Windows includes the AdvaBuild Application Builder, which is the basic 
software module to handle projects, target systems, Circuits and Type Circuits. AdvaBuild 
Application Builder is a prerequisite for AdvaBuild Function Chart Builder and AdvaBuild Bus 
Configuration Builder. 


The communications go through a COM-port or by direct connection through Advant Fieldbus 
100 (the AC55 does not support the AF100 protocol). A direct connection via AF100 is only 
supported if the AF100 option is included in Advasoft for Windows. 
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1.8.5 Basic Functions 


Basic functions include various functions common to installed software as well as 
communication interfaces to proprietary and third-party networks. Each function is summarized 
below. 


1.8.5.1 System Status 


The System Status function allows viewing of hardware and software status for running 
communication links, as well as resetting of diagnostic values presented. Also included are 
communication configuration and symbol resolve functions. 


1.8.5.2 System Messages 


The System Messages function is common for all units in AdvaSoft for Windows and collects 
messages from the units for viewing. The System Messages option is essential to quickly 
localize and correct problems from one of the included components. 


1.8.5.3 Advant Fieldbus 100 Interface 


Advant Fieldbus 100 communication 


The Advant Fieldbus 100 Interface option includes the hardware and software necessary to 
enable communication with Advant Controller 100 series and Advant Controller 400 series on 
the Advant Fieldbus 100 network. 


Configuration files for either Dat Based Objects (COIL files) or Extended DB Element objects 
(BOIL files) are automatically generated for the Advant Fieldbus 100 for all AC 110 using 
AdvaBuild. The configuration files are then manually imported to AdvaSoft for Windows. 


An object configuration tool is provided for mapping and configuration of DAT Based Objects 
to specified AI, AO, DI or DO channels and Event channel information. 


NOTE 


For the Advant Controller 400 series, only DataSet Peripherals (DSP) can be 
used. (Time Tagged Events (TT_Event) and Service Data Protocol (SDP) for 
commands are not supported.) 


Table 1-5 below shows which services are available for applications supported for each object 
type using the Advant Fieldbus 100 Interface. 


Table 1-5. Services provided to application using Advant Fieldbus 100 Interface 


Object type Demand Cyclic Event Command 
AI), AIS®) yes yes no no 

AO"), AOS() yes yes no yes 
DIM), bis() yes yes no no 
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Table 1-5. Services provided to application using Advant Fieldbus 100 Interface (Continued) 


Object type Demand Cyclic Event Command 
DO"), Dos(?) yes yes no yes 
DAT) (3) yes yes no yes 
TT_EVENT() no no yes no 
SYSTEM_STATUS yes yes no no 
MR, MB, MI and MIL) yes yes no yes 


(1) These are DAT Based Elements object types. They are mapped on DAT’s and transferred with 
DataSet Peripherals (DSP) for subscription and Service Data Protocol (SDP) for commands. They 
are configured with the use of the AF100 Configuration Tool. 

(2) These objects are the Extended db version of the Al, AO, DI and DO objects. They are configured 
directly in the Function Chart Builder (FCB). 

(3) Predefined ABB dynamos are not available for DAT objects. 

(4) Time Tagged Events (Event Set) cannot be sent from AC400. The Event Sets must be configured in 
the AC 110. 

(5) These objects belong to the Extended db Elements object group but are mapped towards DAT 
objects. 


1.8.5.4 GCOM Interface 


GCOM communication 


The GCOM Interface option consists of GCOM communication software for communication 
between MS Windows applications and nodes connected to the GCOM network or nodes 
reachable through transit nodes (nodes with both GCOM and MasterBus). No hardware is 
included in the GCOM Interface option. To run GCOM, you must have one IEEE 802.3 
communication board with NDIS interface support installed in your PC. 


Table 1-6. Services provided to application using GCOM Interface 


Object type Demand Cyclic") Event Command 
Al yes yes no no 
AO yes yes no yes 
DI yes yes no no 
DO yes yes no yes 
DAT yes yes no yes(*) 
TT_EVENT®) no no yes no 


(1) Cycle times longer than 30 s are mapped to the standard subscription cycle times 1, 3, 9s. Cycle 
times longer than 30 s are made through cyclic demand subscription. 

(2) Predefined ABB dynamos are not available for DAT objects. 

(3) Time Tagged process Events. 


3BSE 006 236R0301 1-19 


AdvaSoftt’’ for Windows User’s Guide 
Chapter 1 Introduction 


1.8.5.5 SQL*Net TCP/IP for Windows 


The SQL*Net TCP/IP for Windows software option enables AdvaSoft for Windows to access 
data from the Advant Station 500 IMS or ORACLE products (using TCP/IP). You can also 
access data from the Advant Controller 400 Series via an Advant Station 500 Series IMS with 
SQL*Net and AdvaInform SQL*Connect. 


1.8.6 Support for third-party products 


1.8.6.1 Application and communication software 


AdvaSoft for Windows supports any standard software application packages that support DDE. 
You can apply an application package to build your own applications, acquire data from the 
automation system for presentation or reporting purposes, or issue commands to the automation 
system. You can use various types of software applications for these purposes, for example, 
spreadsheets, word processors, databases or MMI packages. 


In addition to the integrated communication options, AdvaSoft for Windows allows you to use 
TCP/IP, Telnet, FTP and X for X Windows. 


1.8.7 Configuration alternatives 


AdvaSoft for Windows can be, as shown in Figure 1-2 and explained in Section 1.1, General 
Information, applied at various network levels in the Advant OCS. It can perform a variety of 
tasks. It can exchange data with all network levels either locally or remotely using Advant 
Station 500 Series Information Management Stations. 

Configuration and operation limits are not discussed here, but are stated in detail in the user’s 
guides for each option in your system. 


Figure 1-6 and Figure 1-7 below show two typical alternatives for AdvaSoft for Windows in one 
configuration. Arrows indicate flow of files or process data. 


sacnerrenies Ld [J S60 Sores in 
Report data, files 
| SQL*Net 


TCP/IP 
DCN 


C ) 


Process values and setpoints 


=| 
=| 


Advant Controller 460 it 


Figure 1-6. Example of an ABB MOD 300 configuration with AdvaSoft for Windows 
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AdvaSoft for Windows with TCP/IP 
and SQL*Net TCP/IP options 


AdvaSoft for Windows 


with GCOM Advant Station 500 Series IMS 


(om) SQL*Net TCP/IP CJ C) 


—— Report data, files ae? 


| ~ | 
Plant Network: MasterBus 300, TCP/IP, GCOM 
| Advant Controller iil | crf | Advant Station [J 
400 Series/MP 200/1 500 Series OS 
| 


a 


Control Network: MasterBus 300 


MasterGate 230/1 


7] 
a4 
>| 

= 


Advant Controller 450 | 


AdvaSoft and 
Advant Fieldbus 100 Interface 


CJ Advant Controller 110 


tt +H tt ... Up to 


Advant Fieldbus 100 80 stations 
Interface | 


scotnolis tr (ocess Values? Fieldbus Network: Advant Fieldbus 100 


Figure 1-7. Example of an Advant OCS configuration with AdvaSoft for Windows 
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1.9 User Interface 


The AdvaSoft for Windows user interface is based on standard Microsoft Windows. It is divided 
into the program groups AdvaCommand, AdvaInform, AdvaBuild and AdvaSoft. 


Refer to the user’s guides for each unit included in your system for a comprehensive guide to the 
user interfaces. 


Figure 1-8 shows an example of the MS-Windows desktop with the AdvaSoft for Windows 
program group and icons for starting each program item. 


Program Manager 
Options Windows Help 


AdvaSoft 


AdvaSoft for © AF100 Object System AF100 1.2/0 
Windows 1.3/0 Config 1.2/0 Messages 


GCOM 1.1/0 


Advalinform 


DDE Server 


AdvaBuild AdvaCommand 


Figure 1-8. AdvaSoft basic functions and Advalnform user interfaces 


1-22 3BSE 006 236R0301 


AdvaSoft™ for Windows User’s Guide 
Section 2.1 Site-Planning Environment 


Chapter 2 Installation 


2.1 Site-Planning Environment 


Before installing AdvaSoft for Windows, make sure that your PC is adapted to house the 
communication boards required. Refer to your PC and hardware manuals to ensure compliance 
with site requirements for your particular installation. 


If you intend to make this installation to upgrade an existing AdvaSoft for Windows installation, 
we recommend that you make sure the old version is uninstalled before starting the installation 
of the new version. You can perform the “uninstallation” using the installation diskettes 
delivered with the old version. 


2.2 Setup 


For instructions on setup for your PC, MS-DOS, Microsoft Windows and other third-party 
applications, see the corresponding user’s guides. 


We recommend that you install all hardware units and third-party software that you plan to use 
with AdvaSoft for Windows before you install AdvaSoft for Windows. Hardware units include 
the PC, the Advant Fieldbus 100 communication board and IEEE 802.3 communication board, 
and the software security key for AdvaCommand, where applicable. If your system includes 
AdvaCommand, Advalnform or optional basic functions, you are prompted to install these. 


2.2.1 Installation procedure 


This section covers how to install the AdvaSoft for Windows basic unit and options. 


1. Insert the diskette named AdvaSoft for Windows, Installation into your floppy disk 
drive. 


2. Select the Run item in the File menu, found in Windows Program Manager. 
3. Type A:\setup. 
4. Click on the OK button. 


An initiation window, belonging to the AdvaSoft for Windows Installation program, is 
displayed during the installation program start-up sequence. The installation program 
starts to extract all the needed files from the installation diskette for the installation. 
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The install/uninstall display appears as shown in the figure below. 


AdvaSoft for Windows Installation 


Select installation option: 


® Install AdvaSoft for Windows 
© Uninstall AdvaSoft for Windows 


7s 


Figure 2-1. AdvaSoft for Windows Installation window 


5. Click on the OK button to accept installation. Alternatively, you can click the Uninstall 
option button and the OK button to uninstall and delete system files for the currently 
installed version. 


The Installation window appears as in Figure 2-2 below. 


— ADVASOFT for Windows Installation 


Install to: 


Ea C:\ADVASOFT Set Location... 


AdvaCommand Development 12000 K 


AdvaCommand Runtime OK 


Advalnform DDE Server 140 K 


AdvaBuild AC 110/70/55 11200 K 


SQL*Net TCP/IP for Windows 10000 K 


Advant Fieldbus 100 Interface 630 K 


GCOM Interface 450 K 


Drive: CA Windows: C:\Windows\ 


Space Required: K K 
Space Available: 10536 K K 


Figure 2-2. AdvaSoft for Windows Installation window 


6. Select each licensed option to install by clicking the corresponding check box. 
7. Click on the Continue button to accept. 


8. See the corresponding user’s guides for the selected licensed options to get more detailed 
information regarding the installation. 


Insert diskettes as prompted until installation is complete. 
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2.3 Shutdown Procedures 


2.3.1 Normal shutdown 


Before shutting down AdvaSoft for Windows, shut down all applications using AdvaSoft for 
Windows. 


To shut down, choose the Exit... item in the File menu or double-click in the upper left-hand 
comer of the main display for each running program. Shutting down the basic unit halts any 
communication between applications and communication options. 


2.3.2 Emergency shutdown 


If a program halts and further control is inhibited, exit all running programs and 

Microsoft Windows by choosing the Exit item in the File menu in each program and on 

the Microsoft Windows desktop. Restart from MS-DOS. Then restart Microsoft Windows and 
AdvaSoft for Windows. 


For a list of error messages and troubleshooting instructions, refer to Chapter 5, Maintenance in 
this and other user’s guides for each option included. 


2.4 Start-up Procedures 
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The AdvaSoft for Windows basic unit and options are started automatically when client 
applications are started, and stopped when the applications are stopped. Double-click each 
program icon to start each program independently. 
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2.5 Product Verification 


2-4 


For verification and information about your AdvaSoft for Windows version, choose the 
About... item in the Help menu from the main window. 


= AdvaSoft for Windows | +] 


File Options Help 


Content 


Figure 2-3. AdvaSoft for Windows main window 


1. Pull down the Help menu from the AdvaSoft for Windows main window. 


2. Select the About... item. 


About AdvaSoft for Windows 


AdvaSoft for Windows Version 1.3/0 


ini Copyright © 1997 ABB Industrial Systems AB 


Figure 2-4. AdvaSoft for Windows Help About window 


3. Click the OK button to close the About window. 
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Chapter 3 Configuration/Application Building 


3.1 Design Considerations 


This chapter gives you the instructions you need to build applications using the DDE Server and 
User API, following installation of third-party products and the basic unit. If you are using one 
of the application software options, refer to corresponding user’s guide(s). 


You can build applications off-line, i.e., without communication running, and can set up and test 
communication directly from the Options menu when necessary. 


You can use the DDE Server to serve third-party client application software such as Microsoft 
Excel. It supports a number of object types as specified in Section 1.8.2.1, AdvaInform DDE 
Server. 


Using the User API, you can fetch object types not supported by, for example, the DDE Server. 


3.2 Capacity and Performance 
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The performance of AdvaSoft for Windows depends on the client application, the 
communication protocol and the PC’s performance. Refer to Section 3.2, Capacity and 
Performance in each user’s guide for information about each option’s performance. 


Cycle times for data update from the automation system are configurable from the application. 
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Technical data 


Table 3-1. Technical data for AF 100 


No. of Advant 
Fieldbus 100 
(C1526) boards 


No. of ports per 
C1526 


Maximum no. of 
tags (objects) 


AdvaSoft for Windows 


1 


2 


30.000 


Table 3-2 below shows recommended and maximum configurations when using AdvaSoft for 
Windows and Advant Controller 110 on Advant Fieldbus 100. 


Table 3-2. Recommended and maximum configurations on AF 100 


No. of hiosot Total no. of | Total no. of 
Configuration guidelines AdvaSoft AC 110 objects on | Event Sets 
AF 100 on AF 100 
Maximum recommended 5 10 5000 50 
configuration 


Table 3-3 below shows recommended and maximum configurations when using AdvaSoft for 


Windows and GCOM 


Table 3-3. Recommended and maximum configurations on GCOM 


Total no. of 
No. of Total no. of . 
Configuration guidelines No-o! transit messages/ Time 
g g AdvaSoft | Caoctt) | eset) | _ Tagged 
Events/sec 
Maximum recommended 4 1 <50'9) 10 
configuration 


(1) 
transit node. 

(2) Examples of messages are: 
- One order signal 


- Data subscription request with 1-16 objects 
- Answer on data subscription which can contain 1-48 objects depending on object type and 


access type. 


Node handling between GCOM and Masterbus. MG 230/1, AC450 or MP200/1 can be used as 


This is valid if a MG230/1 is used as transit node. If you use a 450 or MP200/1 with high CPU 
load as transit node, the message rate will be reduced. 


(3) 
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Valid if a MG 230/1 is used as transit node. If you use an AC 450 or MP 200/1 with high CPU load 
as transit node, then the message rate will be reduced. 
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NOTE 


The number of nodes on the plant network that can have cyclic subscriptions for 
data in a control network is limited in the Master Gate 230/1. By default, you can 
have four nodes with cyclic subscription. 


Do not use AdvaSoft on the plant network if you have more than four nodes on 
the plant network with cyclic subscription. The MasterGate will convert the cyclic 
subscription to demand subscription. This causes extra load in the control 
network because the AdvaSoft station will repeat the subscription request if a 
cyclic response is not received. 


Table 3-4 below shows recommended and maximum configurations when using AdvaSoft for 
Windows and Advant Station 500 IMS through AdvalInform SQL*Connect. 


Table 3-4. Recommended and maximum configurations on SQL*Net TCP/IP 


: : as a No of No of P 
Configuration guidelines AdvaSott | AS 500IMS Read Write 


Maximum recommended 4 1 Yes No 
configuration 


Presentation of attributes from objects such as AI, AO, DI, DO, DAT, PIDCON, RATIOSTN, 
and MANSTATION is possible. 


PC’s used during performance test 
The following Hewlett-Packard PC’s have been used during the performance tests: 


° HP Vectra XU (referred to as XU/48) 
Pentium/90 
540 MB SCSI-2 disk 
48 MB internal RAM 
2 MB video RAM 
Matrox MGA Ultima Plus PCI-graphic 
CI526 communication board 


° HP Vectra XU (referred to as XU/16) 
Pentium/90 
540 MB SCSI-2 disk 
16 MB internal RAM 
2 MB video RAM 
Matrox MGA Ultima Plus PCI-graphic 
CI526 communication board 


° HP Vectra XM2 (referred as XM2/16) 
486/66DX2 
270 MB disk 
16 MB internal RAM 
S3 864-Vision graphic 
CI526 communication board 
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Update time 


A msec 


700 


600 


500 


400 


300—— 


200—— 


100—— 


Advalnform User API 


Mixed 


XM2/16 
— — — XU/16 


DAT (value B, IL, R) 
AI/AO (value, status) 


DI/DO (status) 


_ — AIAO (value, status) 


_ — ~— DI/DO (status) 


l | l l No. of objects 
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Figure 3-1. Cyclic callback performance of Advalnform User API and AF 100 


The total cyclic callback performance of User API via AF 100 is described in the table below. 
The time to execute the cyclic callback is approximately 15 percent of the total cyclic callback 
time. The time for the total cyclic callback given in the curves ensures time for other 
applications to execute under the Windows environment. 


Advalnform DDE Server 


The DDE Server transfers messages between the communication driver and third-party 
applications and acts upon demand from the application. The DDE Server’s performance, 
therefore, depends on the CPU capacity not being used by other applications and on cycle times 
in the application. 


The following times describe the time to update a Microsoft Excel spreadsheet, with dynamic 
data. The times are measured from when you click ‘OK’ to update the data links until all data is 
updated in the spreadsheet. 


NOTE 


The DDE Server is always using symbolic names in the subscription request, i.e., 
a symbolic name translation is always made for all object accesses through the 
DDE Server. 
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The updating time for Microsoft Excel using a one second cycletime is shown in Table 3-5. 


Table 3-5. Start-up subscription performance of Advalnform DDE Server via AF 100 


Excel update time(s) Excel update time(s) 
Number of after initial start-up consecutive requests 
objects QuickLoad=On QuickLoad=On 
XU XU 
8 1 1 
32 1 1 
64 2 2 
124 3 3 
192 4 3 


If you need constant and fast update times, use the QuickLoad function for AF100 the first time 
you call up an object. To activate this function, you have to edit the AdvaSoft.ini file that resides 
in the MS-Windows directory. There you set the QuickLoad item, in the AF100 profile section, 
to On (QuickLoad=On). The QuickLoad function will, during AF100 software start-up, pre- 
load all objects (configured with the AF100 Object configuration tool) into the memory and 
store them there permanently. 


System Messages 


The System Messages application updates messages generated from each application and 
communication program. It has a default size of 100 messages. The newest messages overwrite 
the oldest ones. The messages are stored in the System Messages log file (6S YSTMSG.LOG) on 
the hard disk of your PC. The oldest message is marked with an ‘*’ in the far left-hand column. 
Current position is marked in the top line in the SYSTMSG.LOG file. 


You can configure the maximum size of this file by editing the ADVASOFT.INI file located in 

the directory you specified as your Windows directory. Open the file with a text editor. To allow 
200 messages, insert the following text directly below the [System Messages] section header as 
follows: 


[System Messages ] 
filesize = 200 
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3.2.1 Primary memory requirements 


The recommended primary memory for your PC, i.e., at least 16 MB, is sufficient to run 
AdvaSoft for Windows software on your system. 


3.2.2 Disk storage 


After installation, software options generally require disk space for temporary storage in a 
hidden swap file and temporary files. 


Storage of data created during application building and runtime operations requires disk space. 
Depending on which application program you are using, the System Messages log uses disk 
space as it fills up to its maximum size. Each message requires 257 bytes. The disk space 
required for the default size is shown in the table below. 


Table 3-6. System Messages disk storage requirements 


No. of messages Space required 
100 25KB 


3.3 Application Start-up 


AdvaSoft for Windows and the underlying communication software are normally started 
automatically when a client application is started. Alternatively, you can start AdvaSoft for 
Windows independent of the client application by directly double-clicking the icon to open the 
main menu. 


The System Messages application starts automatically when AdvaSoft for Windows is started. 
Double-click the System Messages icon to view the most recent messages. 


3.3.1 DDE Server 


Normally, you start the client application to start the DDE Server. Alternatively, you can start 
the DDE Server by double-clicking the application icon from the MS-Windows desktop. You 
can minimize the window without stopping the program, as shown in Section 3.6.4, DDE 
Server. 


To start a third-party client application software that is to be used with the DDE Server, 
refer to the corresponding user’s guide. To enable dynamic update of values in a client 
third-party application, the DDE Server must be running. 


See the example of an application given in Section 3.4.1, Application building example with 
MS-Excel. 
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3.4 Tutorial using Advalnform DDE Server 


3.4.1 Application building example with MS-Excel 


To build applications using the DDE Server, a third-party application program supporting DDE 
is required. In this example, MS-Excel is used to: 


° Request data from an AI object in a remote station. 


° Send a command to a remote station. 


NOTE 


It is assumed that installation is complete and the communication used in your 
system is set up as specified in the corresponding user’s guide. 


If you use third-party application programs other than MS-Excel, the default settings of the 
protocol alias definition may not be correct. In this case, set up according to instructions in 
Section 3.5.1, Defining a protocol alias. 


3.4.1.1 Defining the protocol alias 


See Section 3.5.1, Defining a protocol alias. 


3.4.1.2 Cyclic Request for process data 


Use warm DDE links to request process data with dynamic updating. This process data is then 
cyclically updated. Minimum cycle time is one second. 


To create warm DDE links using Microsoft Excel: 
1. Mark the cell where the data is to be placed. 
2. Enter the DDE link definition. 


When the value is needed for the AI object, mark one cell and enter the following DDE 
definition: 


=IMDDE|Prot1_3!AIC21.VALUE 


where Prot1 refers to the alias (see Section 3.5.1, Defining a protocol alias), _3 defines the 
cyclicity in seconds (in this case, 3 seconds), the object name AIC21 refers to the data item 
(separated by the ‘.”), and VALUE is to be collected. 


3BSE 006 236R0301 3-7 


AdvaSoft’ for Windows User’s Guide 
Chapter 3 Configuration/Application Building 


3-8 


The spreadsheet now looks like this: 


Figure 3-2. DDE Link Definition 


B2 =IMDDE|Prott_1!AIC21. VALUE 
oo 
A B c D E F G H 
1 
2 | 
3 
4 
5 
6 
7 


When activated, it takes a while before the data is received. Meanwhile, the cells are marked 


with #N/A as follows: 


Sheet 1 


#N/A 


Figure 3-3. DDE Link Waiting for Data 


After a short time, data is displayed in the selected area as follows: 


Sheet 1 


14.11 


Figure 3-4. Result of DDE Link 


The numbers displayed in the figure above represent the following: 


14.11 is the value of the AI object. 
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3.4.1.3 Demand request for process data 


Cold DDE links are created from Microsoft Excel using the following DDE functions in a 
macro definition sheet: 


1. channel_num =INITIATE(app_text, topic_text) 
Open a DDE channel to the application. 

2. =REQUEST(channel_num, item_text) 
Request the data. 

3. =TERMINATE(channel_num) 
Close the DDE channel. 

4. =RETURNO(O 


A macro to fetch the same value as is given in the previous example, with data displayed by 
column starting at the current cursor position in the worksheet, looks like this: 


Macro 1 


| A | B c D 


1 | Alchan = INITIATE(“IMDDE”;“Prot1”) 
2. | =FORMULA (REQUEST(Alchan;’AIC21.VALUE”);Sheet1!B41) 
3 | =TERMINATE(Alchan) 
4 | =RETURN() 
5 
6 


Figure 3-5. Macro Sheet for a DDE Demand Request 
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3.4.1.4 Sending commands 


You can send data to the Advant OCS using the DDE POKE function. The POKE function has 
the following syntax: 


=POKE(channel_num, item_text, data_ref) 


Creating a sample macro to change the value for AOC21 in an Advant Controller might look as 
follows: 


= Macro 1 
A | B c D 
1 | DSCchan=INITIATE(“IMDDE”;“Prott”) 


2 | =POKE(DSCchan:’AOC21.VALUE”:Sheett !B2) 
=TERMINATE(DSCchan) 


Figure 3-6. Macro Sheet for Transmission of Data with DDE 


When the macro is executed from Sheet1 (Sheet! as the active window), the data in cell B2 
is sent. 
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3.5 Application Procedures 


3.5.1 Defining a protocol alias 
Protocol aliases are used to: 


° Make applications independent of the communication protocol (portable to several 
communications by modifying protocol alias). 


° Define protocol names that third-party applications will accept (for example, 
Microsoft Excel interprets AF100 as a cell reference). 


Protocol Alias Definition 


Alias: 
Prot 


Protocols: Defined Alias: 


Prot1 
Add >> 


Modify 


| eo 


Figure 3-7. An example of protocol alias definition 


1. Open the Protocol Alias Definition dialog box from the Options menu. 
Place the cursor in the Protocols list and type AF100. 

Place the cursor in the Alias edit field and type Prot1. 

Click on the ADD>> button to assign AF100 to Prot1. 

Accept by clicking the OK button. 

Restart AdvaSoft for Windows. 


Se Pe eS 
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3.5.2 Configuring the DDE Server 


Application building using third-party applications that support DDE requires that the protocol 
alias definition configuration of the DDE Server be complete: 
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The Topic Separator text box allows you to enter the separator compatible to your 
third-party application products. Default Topic Separator is “_” (underline). 


The Item Separator text box allows you to enter the separator compatible to your 


Ty) 


third-party application software. Default Item separator is “.” (point or period). 


The Device Timeout text box allows you to enter the time the DDE Server waits for a 
response from the communication handler before issuing a message. Default is 60s. 


Start the DDE Server from the Microsoft Windows desktop. 


Open the DDE Server Configuration dialog box from the Configure menu and enter 
topic separator and item separator for the application software you are using. The default 
settings are compatible with Microsoft Excel. 


NOTE 


MS Excel does not allow all characters to be used as separators, since they might 
be predefined for other functions. 


Example: 


=IMDDE|Prot1_1!AIC21.VALUE 


DDE Server Configuration 


Topic Separator: 


Item separator: 


Device Timeout 60000 mSecs 


Ce Gee Cee 


Figure 3-8. DDE Server Configuration window 


Choose the OK button to accept current values and close window. 
Choose the Cancel button to close and keep old values. 


Choose the Default button to insert default values into the text boxes. 
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3.5.3 Advalnform User API 


The AdvaInform User API (User API) provides a third-generation language (3-GL) interface 
for object access in the Advant OCS. The User API is implemented as a dynamic link library 
(DLL). The User API contains the following functions: 


° AdvaSoft specific functions 
° Basic Support 
° Object Access Services 


The Basic Support section, found in Appendix B, includes help functions and date and time 
functionality. The Object Access Services section, also found in Appendix B, provides 
information on interaction with objects in the Advant OCS. 


3.6 Configuration/Application Building Menus 


3.6.1 File menu 


3BSE 006 236R0301 


AaVa e O OO Vv 


File Options Help 


Figure 3-9. AdvaSoft for Windows File menu 
Exit 


The Exit item returns you to the MS-Windows desktop and the AdvaInform for Windows 
program group. 
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3.6.2 Options menu 
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Each item in the Options menu opens a dialog box. Refer to the user’s guide for each 
communication option for details about their configuration. 


Ate a e e ete Vv 
File Options Help 
Protocol Alias De O 
Configure > 


Communication Status 
Resolve Symbols 


Reset Diagnostics 
ODBC Setup... 


Figure 3-10. Options menu 


Protocol Alias Definition 


The Protocol Alias Definition item enables you to assign aliases to installed communication 
protocols, which are to be used as the protocol name part of the object definition in client 
applications. 


Configure 


The Configure item enables you to configure each installed communication handler. Refer to 
corresponding user’s guides for instructions. 


Communication Status 


See runtime operation menus in the corresponding user’s guide for instructions. 
Resolve Symbols 


The Resolve Symbols item translates all symbols in symbol tables for the protocol chosen. 
The menu closes when symbol resolution is complete. 
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Reset Diagnostics 


See runtime operation menus in corresponding user’s guides for instructions. 


ODBC Setup 
The ODBC Setup item enables you to set up the SQL data sources. 


NOTE 
The ODBC Setup item is only visible if the SQL*Net TCP/IP option is installed. 


3.6.3 Help menu 


— AdvaSoft for Windows |r] 


File Options Help ae 


Contents 


Figure 3-11. Help menu 


Contents 


The Contents item opens the help contents dialog box. 
About 


The About item in the Help menu gives you product verification, confirming version and 
installation information, as explained in Section 2.5, Product Verification. 
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3.6.4 DDE Server 


The DDE Server is started from the AdvaInform for Windows program group. It must be set up 
before you commence application building and must be started before beginning runtime 
operation using your third-party application software. 


3.6.4.1 File menu 


AaVa O b)D : e v A 


File Configure Help 


Figure 3-12. AdvalInform DDE Server main window 


Exit 


The File menu contains the Exit item, which returns control to the MS-Windows desktop. 


3.6.4.2 Configure menu 


AdVa e DID eC eC Vv a 


File Configure Help 


DDE Communication Setup... 


Figure 3-13. Advalnform DDE Server Configure menu 


Use the Configure menu to set up communication-specific data via the DDE Communication 
Setup... item. 
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3.6.4.3 Help menu 


Advalnform DDE Server mig 


File Configure Help 


Figure 3-14. AdvaInform DDE Server Help menu 


The Help menu contains the About item. 


About IMDDE 


Advalnform DDE Server Version 1.0/4 
3] ~~ Copyright© 1997 ABB Industrial Systems AB 


Figure 3-15. Advalnform DDE Server Help About window 


Click the OK button to close the About window. 
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3.7 NetDDE 


3.7.1 Configuring NetDDE Server Support 
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The AdvaInform DDE Server supports the NetDDE feature of Microsoft’s Windows for 
Workgroups software. To configure NetDDE server support on your AdvaSoft for Windows 
node, your Windows for Workgroups environment must have both a NetDDE server node and a 
client node. These nodes must contain applications according to the table below. 


Table 3-7. Net DDE Node Applications 


Net DDE Server Node Net DDE Client Node 


AdvaSoft for Windows DDE-compliant application used 
to request and receive data from 
Advalnform DDE Server Advalnform DDE Server, for 


Configured SYSTEM.INI file example, Microsoft Excel. 


NetDDE addresses use DDEShare names to access a DDE application on a remote server. 
In order to define DDEShare names, you must modify the SYSTEM_INI file on the NetDDE 
server node. You can do this automatically or manually following the instructions below. 


Automatically 


If you have purchased the MS-Windows for Workgroups 3.11 Resource Kit, use the following 
instructions to configure the DDEShare names for AdvaSoft real-time data: 


1. Select the Network DDE Share Manager icon from the MS-Windows for Workgroups 3.11 
Resource Kit program group. The network DDE Share Manager dialog box appears. 


2. Select New from the Share menu. 


3. Complete the dialog box for real-time data using the following table entries: 


Table 3-8. Real-time Data entries 


Dialog box field Real-time Data 
Share Name IMDATA 
Application Name IMDDE 
Topic Name Prott (1) 


(1) NOTE The selected protocol according to topic used in Advalnform DDE 
Server node. 
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Manually 


If you have not purchased the MS-Windows for Workgroups 3.11 Resource Kit, you must 
manually modify the SYSTEM_INI file. Use the following instructions to complete this task. 
Use a text editor to open the SYSTEM_INI file in the MS-Windows for Workgroups directory, 
normally C:\WFW. 


1. Add the following lines to the [DDEShares] section of the file: 
IMDATA=IMDDE, Prot1,,15,,0,,0,0,0 (for real-time values) 


2. Save the changes to the file. 
3. Restart your computer. 


If you are using many different protocols or subscriptions, you can create multiple aliases that 
access Excel but use a different DDEShare name. 


3.7.2 Advalnform DDE Server NetDDE Addresses 
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The NetDDE addressing used to access real-time data in AdvaInform DDE Server is shown 
below: 


Table 3-9. NetDDE addressing 


String Part Real-Time 


Application (or Service) name \\Server Name\NDDE$ 


Topic name IMDATA 


Item name ObjectName.AttributeName 


An example of the syntax used to transfer real-time data is: 
='\\ABC\NDDES’ | IMDATA!AI1.VALUE 


Where: 

ABC is the computer or workstation name 
NDDE$ indicates that NetDDE is used 

IMDATA is the DDEShare name for real-time data 


AI1.VALUE is the item name. 
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Chapter 4 Runtime Operation 


4.1 Product Operation 


Operation Mode 


To operate AdvaSoft for Windows products, Windows must run in 386 enhanced mode. 
If you are not sure if your Windows runs in 386 enhanced mode, you can obtain more 
information by choosing Help About in the Program Manager. 


Runtime Operation 


AdvaSoft for Windows and the System Messages application automatically start when any 
client application is started. You can start it separately by double-clicking the program icon. 
It is normally stopped by stopping the client application. Alternatively, you can stop it by 
closing AdvaSoft for Windows. 


To enable exchange of data with the automation system, AdvaSoft for Windows, the 
communication option and the client application must be running. If other applications under 
Microsoft Windows are running, performance may be jeopardized. 


4.2 Operating Overview 


3BSE 006 236R0301 


During runtime operation, AdvaSoft for Windows acts as an interface between the client 
application and the communication software and hardware included in your system. 

This section includes information about operation of the System Messages application and 
System Status, as well as an overview of available options. 
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4.2.1 Basic unit 


System Messages 


The System Messages application updates the message list from running software during 
application building and runtime. You can view it by switching to it from any application during 
application building and runtime. 


System Status 


System Status updates status of running communication links. You can view it in the AdvaSoft 
for Windows program. 


4.2.2 Options 


4.2.2.1 AdvaCommand Runtime 
AdvaCommand provides presentation displays and dialogs for control of the process with 
standard and user-defined process and object displays, as well as event and alarm lists and 
historical data. 


4.3 Runtime Tutorial 
Not supplied. 


4.4 Operating Instructions 


During runtime, the System Messages application and System Status included in the basic unit 
are applicable. For runtime operating instructions, refer to the user’s guides for each application 
software package included in your system. 
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4.4.1 Viewing the System Status 


= AdvaSoft for Windows 


File Options Help 
Protocol Alias Definition... 
Configure 


Communication Status AF100 
Resolve Symbols 


Reset Diagnostics 


Figure 4-1. AdvaSoft for Windows Options menu when using the AF100 communication option 


To view the System Status, do the following: 

1. Check that the communication on your system is running. 
Start AdvaSoft for Windows. 

Choose the Options menu. 


Choose the Communication Status item. 


Cus ae Es 


Click the communication option/options presented (should be running) and confirm by 
clicking status information. 


For details on status messages, refer to the relevant user’s guide for your communication 
software. 


4.4.2 Reset Diagnostics 


Pull down the Options menu, then choose Reset Diagnostics, followed by the communication 
handler from the list. Also see Section 4.5.1, File menu. 
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4.5 Runtime Operation Menus 


4.5.1 File menu 


The File menu contains the Exit item, which you can use to terminate AdvaSoft for Windows. 


4.5.2 Options menu 
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— AdvaSoft for Windows L~] 
File Options Help 
Protocol Alias Definition... 
Configure 
Communication Status AF100 
Resolve Symbols 


Reset Diagnostics 


Figure 4-2. AdvaSoft for Windows runtime menu using the AF100 communication option 


Communication Status 


The Communication Status for the interface chosen from the list presented to the right of the 
menu opens a status window showing communication specific information. 


Resolve Symbols 


Resolve Symbols updates symbol tables so that all objects can be subscribed to by a client 
application. 


Reset Diagnostics 


Resets Diagnostics resets the diagnostics for the communication interface chosen from the list 
to the right of the menu. For further information, see related communication user’s guide. 
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4.5.3 Help menu 


The About item in the Help menu is for verification of the software version of the System 
Messages application. 


4.5.4 System Messages 


The System Messages application updates messages from running applications and 
communication interfaces. The Date and Time field states the time of reception in the System 
Messages log. Severity states if the message is an “E” for Error, “W” for Warning or “TI” for 
Information. Program Name states the source of the message. For troubleshooting, refer to 
Section 5.4, Fault-Finding and User Repair. 


e Vv A 
File Options Help 
Date and Time - Severity - Program Name Message text -> 
15/02/94 15:04:59 | DDE Server Creating Topic. Calling ||@ 
15/02/94 15:04:59 | DDE Server Creating Topic Calling 
15/02/94 15:04:59 | DDE Server Creating Topic. Calling 
* 15/02/94 15:05:00! DDE Server Reading Device Timeout 
§ 
@ »> 


Figure 4-3. System Messages application Window 


4.5.4.1 File menu 


The File menu contains Save, which saves all error messages in the System Messages, and 
contains Exit, which terminates the System Messages application. 


4.5.4.2 Options menu 


The Always on top item ensures that, when checked, the System Messages window is always 
visible on the screen during a work session with multiple program windows. 
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4.5.4.3 Help menu 


The About item in the Help menu is for verification of the software version of the System 
Messages application. 


About System Messages 


System Messages Version 1.0/2 


Copyright © 1997 ABB Industrial Systems AB 


Figure 4-4. System Messages application Help About window 


Click the OK button to close the About window. 
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Chapter 5 Maintenance 


5.1 Preventive Maintenance 


There are several measures you can take to ensure system availability and specified 
performance. A PC that offers both good quality and adequate performance is recommended. 
In addition, preventive maintenance procedures are important, especially if you are running 
several applications. 


Refer to MS-Windows and MS-DOS user’s guides for more information. 


Memory management 


Be sure to set up your PC’s memory for the applications on your system. Using Microsoft 
Memmaker is a safe and easy way to analyze and set up memory for optimum operation. 


Backup routines 


We recommend that regular backup data be created during application building and runtime 
operation. For references regarding which files are influenced during application building and 
runtime, see Chapter 3, Configuration/Application Building of each user’s guide. 


Virus protection 


We recommend regular use of a virus-detection program. One is included in Microsoft DOS 6.0 
or later. 


Hard disk management 


Over time, fragmentation reduces hard disk performance. We recommend you use a 
defragmentation program, e.g., defrag.exe included in DOS 6.0 or later. Avoid using 
MS-DOS Doublespace together with AdvaCommand. 


5.2 Hardware Indicators 
Not applicable. 


5.3 System messages 


System messages are generated by the different AdvaSoft for Windows hardware and software 
and are written to the System Messages log. The system messages, their cause and 
recommended actions are included in Chapter 5, Maintenance of each user’s manual. 
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5.4 Fault-Finding and User Repair 


5.4.1 Troubleshooting 


5.4.1.1 Help menus for application building 


5.4.1.2 System Status 


To get help from application software during application building, press <F1>, which gives you 
help on the current topic you are using, where applicable. To find help on specific topics, select 
the Help menu, then items Search, Show Topics or Index. 


The System Status shows the status of communication options that are running. Refer to the 
user’s guide for the communication option on your system for details. 


5.4.1.3 System Messages 


The System Messages application identifies errors from the installed AdvaSoft for Windows 
software and hardware and shows their severity, their source and the time they occurred. 
For more detailed information and recommended action for each error, refer to Section 5.3, 
System messages in each AdvaSoft for Windows user’s guide. 


5.4.2 How to get support from ABB 


5-2 


If you have questions about, or problems with, your AdvaSoft for Windows product, please 
check in the user’s guide for the respective unit or go to the Help menu. If your question is not 
answered, contact your local ABB representative responsible for this product. If you have 
questions on any third-party products, contact the product support services responsible for these 
third-party products. 


If you encounter errors or if you have suggestions to improve the AdvaSoft for Windows 
product, please contact your local ABB Industrial Systems AB representative. 


When you submit a problem report, it is imperative that you reconstruct the events leading to the 
problem so we can speedily resolve it. Therefore, please attach any relevant supplementary 
information, e.g., changes to your system or events prior to the problem. Printouts of System 
Message logs and hard copies of configuration displays are often crucial. 
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Appendix A References 


A.1 ADVASOFT.INI 


[Communication] 
Protocols=GCOM, AF100 


[User Name] 
GCOM=PROT1 


[INSTALLATION] 

ADVADIR=C: \ADVASOFT 

Version=1.3/0 

UserName=PC18 

UserCompany=ABB Industrial Systems 


[ IMDDE] 
ItemSeparator=. 
TopicSeparator=_ 


[AF100Profile] 
(see the Advant Fieldbus 100, AdvaSoft for Windows, User’s 
Guide) 


[GCOMProfile] 
(see the GCOM Interface, AdvaSoft for Windows, User’s Guide) 


[AdvaCommand] 
(see the AdvaCommand for Windows, User’s Guide) 


[Installed] 

Comp_1=Basic functions 1.3 

Comp_2=AdvaCommand Development 1.2 

Comp_3=AdvaInform DDE Server 1.0/4 

Comp_4=Advant Fieldbus 100 Interface 1.2 

Comp_5=ORACLE SQL*Net for TCP/IP & ODBC for Windows 2.0 
Comp_7=GCOM Interface 1.1 
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Appendix B References 


B.1 Advalnform User API 


The functions described below are included in the USERAPI.DLL. These functions allow you 

to develop BU or customer-specific applications. The User API is designed to allow you to also 
implement portable applications for use in Advant Station 500 Series Information Management 
Stations (AS 500IMS). The AdvaInform User API for AdvaSoft is a subset of the AdvaInform 
User API for AS SOOIMS. 


The AdvaInform User API in AdvaSoft for Windows is divided into three different groups: 
° AdvaSoft extension 

° Basic Support 

° Object Access Services 


The User API Dynamic Link Library (DLL) is built using Visual C++ 1.5 with the “Large” 
memory model. All files that are necessary to include reside in the /advasoft/typedir directory. 
Note the following important compiler settings: 


° Use “Large” memory model 

° SS != DS, DS NOT loaded on function entry 
° Protected Mode DLL functions 

° Use 2 byte alignment 


The Object Access Services functions exist in two versions: wiuxxx and bcixxx. The wiuxxx 
functions allow the application to direct the call to a specific communication handler, through a 
protocol name parameter. They also allow shortcut references to objects for fast access. 

The bcixxx functions provide compatibility with the AS 5OOIMS Advalnform User API 
functions. Use against only one communication handler is, however, limited through the User 
API (the first defined in the [Communications] section of the ADVASOFT.INI file). 


B.1.1 AdvaSoft extensions 


These extensions are specific to the AdvaSoft for Windows environment. The wiuInitHandler 
must be called before you use the other User API functions. The wiuTerminateHandler must be 
called before you terminate the application. 
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B.1.1.1. Init communication handlers 
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NAME: wiulInitHandler - initiate the communication handlers. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


void pascal wiuInitHandler(void); 


PARAMETERS 


None. 


DESCRIPTION 


The wiuInitHandler function is used to allow each related communication handler to initialize 
itself and the corresponding communication interface (software and hardware). This function 
must be called once by an application prior to all other access to the User API. 

The corresponding function, wiuTerminateHandler, is used to release and terminate each 
communication handler. 


RETURN VALUE 


WiuSuccess if initialization was successful, WiuFailed if initialization failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult result; 
result = wiulnitHandler(); 
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B.1.1.2 Configure communication handler 
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NAME: wiuConfigHandler - opens the configuration dialog for specified communication 
handler. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult pascal wiuConfigHandler( char* protName, HWND hwnd ); 


PARAMETERS 

protName [in] name of communication handler to configure. The protocol name is 
found in the [Communications] section of the ADVASOFT.INI file. 

hwnd [in] window handle of calling application’s main window. 

DESCRIPTION 


The wiuConfigHandler function is used to allow an application to call a communication 
handler’s configuration dialog function. This function is optional; the configuration dialog is 
reachable from the AdvaSoft main program Options menu. 


RETURN VALUE 


WiuSuccess if the dialog call was successful, WiuFailed if the dialog call failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult result; 


result = wiuConfigHandler (“Myprotocol”, myHwnd) ; 
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B.1.1.3 Resolve Symbols 
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NAME: wiuResolveSymbols - resolve all symbols used for a communication handler. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult pascal wiuResolveSymbols( char* protName ),; 


PARAMETERS 

protName [in] name of communication handler to resolve. The protocol name is 
found in the [Communications] section of the ADVASOFT.INI file. 

DESCRIPTION 


The wiuResolveSymbols function is used to allow an application to force a communication 
handler to resolve all previously used symbols. This function is optional; the resolve function is 
reachable from the AdvaSoft main program Options menu. 


RETURN VALUE 


WiuSuccess if retranslation was successful (or successfully started), WiuFailed if the 
retranslation failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult result; 


result = wiuResolveSymbols (“Myprotocol”); 
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B.1.1.4 Display Communication Status 
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NAME: wiuDisplayStatus - displays status information related to the communication 
interface. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult pascal wiuDisplayStatus( char* protName, HWND hwnd); 


PARAMETERS 

protName [in] name of communication handler to display status for. The protocol 
name is found in the [Communications] section of the ADVASOFT.INI 
file. 

hwnd [in] handle of main window in calling application. 

DESCRIPTION 


The wiuDisplayStatus function is used to allow an application to display status information 
related to a communication handler. This function is optional; the function is reachable from the 
AdvaSoft main program Options menu. 


RETURN VALUE 


WiuSuccess if function call was successful, WiuFailed if the function failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


HWND hwnd; 
WiuResult result; 


result = wiuDisplayStatus (“Myprotocol”, hwnd); 
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B.1.1.5 Reset Diagnostics 
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NAME: wiuResetDiagnostics - resets diagnostic information related to a communication 
interface. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult pascal wiuResetDiagnostics( char* protName), 


PARAMETERS 

protName [in] name of communication handler to reset. The protocol name is found 
in the [Communications] section of the ADVASOFT.INI file. 

DESCRIPTION 


The wiuResetDiagnostics function is used to allow an application to reset diagnostics 
information related to a communication handler. This function is optional; the reset function is 
reachable from the AdvaSoft main program Options menu. 


RETURN VALUE 


WiuSuccess if function call was successful, WiuFailed if the function failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult result; 


result = wiuResetDiagnostics (“Myprotocol”) ; 
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B.1.1.6 Terminate communication handlers 
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NAME: wiuTerminateHandler - terminates the communication handlers. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult pascal wiuTerminateHandler( void); 


PARAMETERS 


None. 


DESCRIPTION 


The wiuTerminateHandler function is used to allow each related communication handler to 
terminate itself and the corresponding communication interface (software and hardware). 
This function must be called once by an application prior to exiting the application. 

The corresponding function, wiuInitHandler, is used to initiate each communication handler. 


RETURN VALUE 


WiuSuccess if termination was successful, WiuFailed if termination failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


WiuResult result; 


result = wiuTerminateHandler(); 
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B.1.1.7 Allocate memory 
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NAME: wiuMalloc - allocate global memory. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


char* pascal wiuMalloc( unsigned long size); 


PARAMETERS 


size [in] size (in bytes) of buffer to allocate. 


DESCRIPTION 


The wiuMalloc function is used to allocate global memory buffers. Each call to this function 
allocates one memory handle, which is a limited resource in Windows (total number of handles 
is 8192). It is recommended that you group your data buffers together to minimize the allocated 
memory handles. 


RETURN VALUE 
Pointer indicating the allocated buffer, NULL if failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


char* buffer; 


buffer = wiuMalloc(100); 
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NAME: wiuFree - free allocated global memory. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


void pascal wiuFree(char* buffer); 


PARAMETERS 


buffer [in] pointer to buffer to free. 


DESCRIPTION 
The wiuFree function is used to free global memory allocated by wiuMalloc. 
RETURN VALUE 


None. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


char* buffer; 
buffer = wiuMalloc(100); 


wiuFree (buffer); 
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B.1.1.9 Reallocate memory 
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NAME: wiuRealloc - reallocate global memory. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


char* pascal wiuRealloc( char* buffer, unsigned long size) 


PARAMETERS 

buffer [in] pointer to buffer to reallocate. 

size [in] new size (in bytes) of buffer to reallocate. 
DESCRIPTION 


The wiuRealloc function is used to reallocate global memory buffers allocated by wiuMalloc. 
RETURN VALUE 
Pointer indicating the allocated buffer, NULL if failed. 


EXAMPLE 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


char* buffer; 
buffer = wiuMalloc(100); 


buffer = wiuRealloc(buffer, 200); 
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B.1.2 Basic Support 


B.1.2.1 Get System Time 
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NAME: bciGetSystemTime - get the system time as a time stamp. 


SYNOPSIS 
#include <bciUAPI.h> 
typedef long BciInt32; 


typedef struct BciTimeStamp 
{ 


time_t seconds; 
Bcilnt32 microSeconds; 
BciTimeStamp; 


} 


void pascal bciGetSystemTime(BciTimeStamp* systemTime); 


PARAMETERS 


systemTime [out] encoded system time. 


DESCRIPTION 


The bciGetSystemTime function is used to get the current system time as a time stamp value. 
The time stamp is global in the system and does not include time zone correction. The time 
stamp can be broken down into date and time components using the services 
bciGetStandardTime and bciGetLocalTime. 


RETURN VALUE 


None. 


EXAMPLE 
#include <bciUAPI.h> 


BciTimeStamp time; 
bciGetSystemTime( &time ); 
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B.1.2.2 Get Local Time 
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NAME: bciGetLocalTime - get the local calendar time. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <time.h> 


typedef long Bcilnt32; 


typedef struct BciTimeStamp 

{ 
time_t seconds; 
Bcilnt32 microSeconds; 
BciTimeStamp; 

} 


void pascal bciGetLocalTime(BciTimeStamp* systemTime, 
struct tm* localTime, 
Bcilnt32* microSeconds), 


PARAMETERS 

systemTime [in] | encoded system time. 
localTime [out] date and time components. 
microSeconds [out] the microseconds component. 
DESCRIPTION 


The bciGetLocalTime function is used to convert systemTime to local calendar time, broken 
down into date and time components. The local time is the calendar time expressed for a specific 
time zone. Verify the setting of the Time Zone environment variable TZ. 


The ANSI C format of the date and time components is used. This means that you can use the 
ANSI C function strftime to convert to text format in a native language. 


RETURN VALUE 


None. 


EXAMPLE 
#include <bciUAPI.h> 
#include <time.h> 


BciTimeStamp sysTime; 
tm localTime; 
BcilInt32 micros; 


bciGetSystemTime( &sysTime ); 
bciGetLocalTime( &sysTime, &localTime, &micros ); 
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B.1.2.3 Get Standard Time 
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NAME: bciGetStandardTime - get the standard (UTC) calendar time. 


SYNOPSIS 


#include <bciUAPI.h> 
#include <time.h> 


typedef long Bcilnt32; 


typedef struct BciTimeStamp 

{ 
time_t seconds; 
Bcilnt32 microSeconds; 
BciTimeStamp; 

} 


void pascal bciGetStandardTime(BciTimeStamp* systemTime, 
struct tm* standardTime, 
Bcilnt32* microSeconds), 


PARAMETERS 

systemTime [in] encoded system time. 
standardTime [out] date and time components. 
microSeconds [out] the microseconds component. 
DESCRIPTION 


The bciGetStandardTime function is used to convert systemTime to normalized calendar time, 
broken down into date and time components. The normalized calendar time is global in the 
system and does not include time zone correction. Coordinated Universal Time (UTC) is used. 


The ANSI C format of the date and time components is used. This means that you can use the 
ANSI C function strftime to convert to text format in a native language. 


RETURN VALUE 


None. 


EXAMPLE 
#include <bciUAPI.h> 
#include <time.h> 


BciTimeStamp sysTime; 

tm UTCTime; 

BeilInt32 micros; 

bciGetSystemTime( &sysTime ); 

bciGetStandardTime( &sysTime, &UTCTime, &micros ); 
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NAME: bciSendMessage - send a system message to the message logger. 


SYNOPSIS 
#include <bciUAPI.h> 


typedef enum BciSeverity 

{ 
bciINFROMATION, 
bciWARNING, 
bciERROR, 
bciFATAL 

} BciSeverity; 


typedef enum BciAudience 

{ 
bciOPERATOR, 
bciENGINEER, 
bciSERVICE, 
bciDEBUG 

} BciAudience; 


void pascal bciSendMessage( int component, 
int messageNumber, 
const char* objectName, 
const char* fileName, 
int lineNumber, 
BciSeverity severity, 
BciAudience audience, 
int datal, 
int data2, 
const char* textData); 


PARAMETERS 

component [in] number of the user application. 
messageNumber [in] number of the message text. 
objectName [in] name of the program files (__FILE_). 
fileName [in] name of the Application or Object. 
lineNumber [in] line number in the program file (__.LINE_). 
severity [in] level of the error. 

audience [in] intended audience for the message. 
datal [in] application data. 

data2 [in] application data. 

textData [in] application data. 
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DESCRIPTION 
The bciSendMessage function is used to send a message to the system message logger. 


The component and messageNumber identify the message text that is picked up from the 
message file. These parameters are currently not used in AdvaSoft for Windows and should 
always be set to 0 (zero). 


The fileName and lineNumber should identify where the message is generated in your code. 


The severity argument indicates whether the message reports a Fatal condition (which renders a 
node or a major subsystem unusable), an Error condition (which causes failure of an individual 
action but does not affect subsequent actions), a Warning (which reports a potential problem) or 
Information (either a recovery from an error condition, a successful conclusion to an activity 
which cannot be reported to the user any other way, or any other indication to the user which 
does not require a response). 


The audience argument indicates the level of user for which the message is intended. 


The extra data arguments make it possible for you to supply more information about the cause 
of the message. 


The objectName, severity, datal, data2 and textData are shown together with the Date and Time 
in the System Messages log. 


It is recommended you use string table resources for storage of message strings to ensure 
multiple languages can be supported. 


RETURN VALUE 


None. 


EXAMPLE 

#include <bciUAPI.h> 
#include <errno.h> 
#include <fcntl.h> 


int fd; 
fd = open( “mydatafile”, O_RDONLY ); 
if (fd == 0) 


bciSendMessage(0, 3, myApplicationName, FILE, LINE, 
bciERROR, bciENGINEER, errno, 0, 
“Failed to open mydatafile™ ); 
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B.1.2.5 Get Local Node 
NAME: bciGetLocalNode - get local network and node number (portable). 


NAME: wiuGetLocalNode - get local network and node number (not portable). 


SYNOPSIS 
#include <bciUAPI.h> 


void pascal bciGetLocalNode(unsigned int* localNetwork, 
unsigned int* localNode); 


void pascal wiuGetLocalNode( const char* protName, 
unsigned int* localNetwork, 
unsigned int* /ocalNode); 


PARAMETERS 

protName [in] specifies which protocol handler to use (wiu specific). 
localNetwork [out] number of the local network. 

localNode [out] number of the local node. 

DESCRIPTION 


The bciGetLocalNode function is used to retrieve the network and node number of the local 
node. Depending on bus type, the network and node number may differ within the same station. 
The wiuGetLocalNode function provides the network and node number configured for each 
individual protocol. 


RETURN VALUE 


None. 


EXAMPLE 
#include <bciUAPI.h> 


unsigned int localNet; 
unsigned int localNode; 
bciGetLocalNode(&localNet, &localNode) ; 
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B.1.3 Object Access Services 


The Object Access Services functions consist of a number of array parameters used to refer to 
the accessed objects and their attributes. The figure below gives you an overview of the 
parameters used in the Object Access Services functions. 


const char** objectNames —ge-| ObjectName 1 
Object name 2 
const int* attrioutes pst AttrID1 || srtarrailres 
AtrID2 Data from 
AttrID3 |. Controller 
AttrID 4 ieee 
AttrID 5 ‘ieee AttrPtr? Valuet 
Abe AttrPtr2 pe Value2 
AtrID7 | rPtr alue 
fel I 4 
AttrID 8 = AttrPtr4 -& Value4 
; | AttrP L Val 
size_t* valueSizes t————_}a ValSize 1 as ttrPtrS alue5 
; 4 awe |) AttrPtr6 Be Value6 
ValSize 2 LH L 
ee eee Kee Value7 
ValSize 3 ae as 
| ——_ [attrPtr 8 Value8 
ValSize 4 
ValSize 5 
am AttrPtr 1 Be Valuet 
ValSize 6 |— | 
a AttrPtr 2 pe| Value2 
ValSize 7 ee an 
AttrPtr 3 BH Value3 
ValSize 8 
AttrPtr 4 B| Value4 
void*** values | —_______ el Opjval 1 AttrPtr 5 pe! Valued 
ObjVal 2 AttrPtr 6 Be Value6 
Bei eaiea ey AttrPtr 7 Be Value7 
ciStatus* status 
9 AttrPtr 8 pe Values 
Status 2 te 
Shared memory — 
unsigned long int* objRef —gy! ObjRef 1 
: = Object Type related parameter 
ObjRef 2 


= Object Instance related parameter 


It is important that the value and status buffers be globally shared and allocated (preferably, 
using the wiuMalloc function), since these will probably be written to by another process. 
The other parameters may be temporarily allocated on the stack. 


For a detailed description of the object types, refer to the Advalnform Object Types Reference 
Manual. 
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B.1.3.1 Get Object Type 
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Calling Name 


NAME: bciObjectType - resolve objects and get their types (portable). 


NAME: wiuObjectType - resolve objects and get their types (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciObjectType( const char** objectNames, 
int objectCount, 
char*** objectTypeNames); 


Advalnform for Windows specific: 


BciStatus pascal wiuObjectType( char* protName, 
const char** objectNames, 
int objectCount, 
const char*** objectTypeNames, 
unsigned long int* objectRef ); 


PARAMETERS 
protName [out] 
objectNames [in] 
objectCount [in] 


objectTypeNames [out] 


objectRef [out] 


DESCRIPTION 


specifies which protocol handler to use (wiu specific). 


array with names of the object instances to get object type for 


number of object names in the objectNames array. 


array with names of the object types. If object name is 
unresolved, the type name is a NULL string. 


array with application-specific references to objects 
(wiu specific). 


The bciObjectType function resolves a number of object instance names and retrieves their 
object type names. The objectCount parameter defines the size of the objectNames and 
objectTypeNames arrays. The object type name strings in the objectTypeNames array and the 


objectTypeNames array are allocated by the bciObjectType function. 
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You can use the protName in wiuObjectType in two ways: 


a. Specify to User API which communication handler to ask for the object type 
name(s). 


b. Force User API to ask each communication handler for the object type name, and 
return corresponding protocol name (only possible for one object at a time). 


In a) you specify the protocol name in the string passed to the User API. In b) you provide an 
empty string, which is filled in by the User API with the protocol name related to the object. 
If you use b), you can only call the function with one object at a time. 


You can use the objectRef in wiuObjectType to retrieve a shortcut handle to the objects. 

Use this objectRef in further calls to the User API for fast access to the related objects. 

This requires, however, that the objNames array in these calls (bciGetAttr...) be a NULL pointer 
to indicate to the User API that the shortcut reference should be used. 


You can also use the objectRef for storage of a pointer or reference to your own application data 
structures for the related object. In this case you fill in the objectRef data yourself, and must 
provide the objectNames in all calls to the Object Access Services. 


RETURN VALUE 


BciStatus, giving the status of the function call. Upon normal, non-error return of a User API 
function, the function returns the value beiSUCCESS (1). The following error codes can be 
returned by the User API in AdvaSoft for Windows: 


° bciNOT_SUPPORTED (the function or object type is not supported) 
° bciINCONSISTENCY (some problem with the parameters used) 


° bciALLOCATION (the User API or communication handler cannot allocate required 
resources) 


° bciUNRESOLVED (symbol not resolved). 


EXAMPLE 


The following example resolves and retrieves the object type of three objects: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus apiStatus; 
const char* objNames[3] = { “AI1_T”, “DI2_T”, “AO3_T” }; 
char** objTypeNames; 


apiStatus = bciObjectType( objNames, 3, &objTypeNames ); 


if (apiResult != bciSUCCESS) 
MessageBox( NULL, “API Status Error”, “Test”, MB_OK ); 
else 


MessageBox( NULL, “Successful”, “Test”, MB_OK ); 
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B.1.3.2 Get Object Type Attributes 


Calling Name 
NAME: bciObjTypeAttributes - attribute info for a specific object type (portable). 
NAME: wiuObjTypeAttributes - attribute info for a specific object type (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


typedef enum BciDataType; 
typedef unsigned short BciDataTypelIndex; 


BciStatus pascal bciObjTypeAttrs(const char* objectTypeName, 
int* attributeCount, 
char*** attributeNames, 
size_t** attributeSizes, 
int** attributeTypes, 
int** attrTypelndexes); 


Advalnform for Windows specific: 
typedef enum BciDataType; 
typedef unsigned short BciDataTypelIndex; 


BciStatus pascal wiuObjTypeAttrs(const char* protName, 
const char* objectTypeName, 
int* attributeCount, 
char*** attributeNames, 
size_t** attributeSizes, 
int** attributeTypes, 
int** attrTypelndexes); 


PARAMETERS 
protName [in] specifies which protocol handler to use (wiu specific). 
objectTypeName [in] name of the object type for which attribute information is sought. 


attributeCount  [inout] number of attributes in the attribute arrays returned. 


attributeNames [out] array with the attribute names. 
attributeSizes _ [out] array with the attribute data type sizes. 
attributeTypes [out] array with the attribute data type identifiers. 
attrTypelndexes [out] array with the attribute data type indexes. 
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DESCRIPTION 


The bciObjTypeAttrs function retrieves type directory information regarding the attributes for 
a named object type. The attributeCount parameter defines the size of all output arrays, which 
should be allocated and updated upon return to the actual number of attributes defined for the 
object type. The attribute name strings in the attributeNames array are allocated by the 
bciObjTypeAttrs function. They are not guaranteed to contain the same information 
throughout the execution. They must, therefore, be copied into user variable for permanent use. 


RETURN VALUE 
BciStatus giving status of the function call. 


The BciDataType type used by the. . . Type parameter in User API functions, identifies the 
type of data for the attribute/operation/event/element. 


EXAMPLE 
The following example retrieves attribute information from the object type name “AT”: 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus apiStatus; 


char* objTypeName = { “AI” }; 
int attrCount; 

char** attrNames; 

int* attrTypeIndexes; 
size_t* attrSizes; 

int* attrTypes; 


apiStatus = bciObjTypeAttrs( objTypeName, 
&attrCount, 
g&attrNames, 
éattrSizes, 
é&attriTypes, 
é&attrTypeIndexes ); 
if (apiStatus != bciSUCCESS) 
MessageBox( NULL, “API Status Error”, “Test”, MB_OK ); 
else 
MessageBox( NULL, “Successful”, “Test”, MB_OK ); 
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B.1.3.3 Get Attribute Values once 


Introduction 


The purpose of this function is to read attribute values from object instances once. 


Calling Name 


NAME: bciGetAttributes - get data once (portable). 


NAME: wiuGetAttributes - get data once (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


Advalnform User API in general: 


BciStatus pascal bciGetAttributes( const char** objectNames, 


int objectCount, 

const int* attributes, 

int attributeCount, 
const size_t* valueSizes, 
void*** values 
BciObjStatus* status); 


Advalnform User API for Windows specific: 


BciStatus pascal wiuGetAttributes(const char* protName, 


PARAMETERS 


protName 


objectRef 


objectNames 


objectCount 
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[in] 


[in] 


[in] 


[in] 


unsigned long int* objectRef, 
const char** objectNames, 
int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 
void*** values 
BciObjStatus* status); 


specifies which protocol handler to use (wiu specific). 


array with application-specific references to objects 
(wiu specific). 


array with names of object instances from which attribute 
values are sought. 


number of object names in the objectNames array. 
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attributes [in] array with attribute identifiers from which to get values. 
attributeCount [in] number of attribute identifiers in the attributes array. 
valueSizes [in] sizes of the areas where the attribute values are stored. 

values [inout] array of pointers to array with pointers to data areas where the 


attribute values are stored. 


Status [out] array of status, one status per object. 


DESCRIPTION 


The bciGetAttributes function gets a number of attribute values from a number of object 
instances of the same object type. The attribute identifiers in the attributes array are obtained 
from an object type include file. The object type include file is also used to get the data types of 
the attribute values. The bciGetAttributes function verifies that the requested attributes are part 
of the object type the object instances belong to and that the valueSizes are correct. 

The bciGetA ttributes function cannot verify that the correct data types are used for the 
attribute values. That is the caller’s responsibility. 


NOTE 


The User API will wait in a Yield loop until data is received or until timeout. 
Do not use this function if your application is called from other applications for 
data retrieval because of the risk of reentrance problems. 


RETURN VALUE 


The BciStatus return type returned by most User API functions identifies the status of the User 
API function call and its parameters. 


Upon normal, non-error return of a User API function, the function returns the value 
bciSUCCESS (1). The User API can return the following error codes : 


° bciNOT_SUPPORTED (the function or object type is not supported) 
° bciINCONSISTENCY (a problem with parameters used) 

° bciALLOCATION (the User API cannot allocate required resources) 
° bciUNRESOLVED (symbol not resolved) 

° bciTIMEOUT (timeout in request). 


EXAMPLE 


The following example gets two attribute values from three AI objects: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 
#include <omf_AI.h> 


#define NR_OBJS 3 
#define NR_ATTR 2 
#define OBJNAMLEN 21 
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int ag 

BciStatus apiResult; 

static char* aiObjNames[NR_OBJS] = {‘AI1”,”AI2"”,”AI3"}; 

int aiAttributes[NR_ATTR] = {OMF_AIVALUEID, 
OMF_ATSTATUSID}; 

size_t aiValueSizes[NR_ATTR] = {sizeof( Omf_AIVALUE ), 

sizeof( Omf_AISTATUS )}; 
void** aiValues [NR_OBJS]; 
void* aiValuesRef [NR_OBJS] [NR_ATTR]; 


BciObjStatus* aiObjStatus;// Must be allocated globally 
Omf_AIVALUE* aiObjValue; // Must be allocated globally 
Omf_AISTATUS* aiStatus; // Must be allocated globally 


aiObjStatus= 

(BciOb jStatus*)malloc (sizeof (BciObjStatus) *NR_OBJS) ; 
aiValue=(Omf_AIVALUE*) wiuMalloc( sizeof (Omf_AIVALUE) *NR_OBJS) ; 
aiStatus=(Omf_AISTATUS*) wiuMalloc (sizeof (Omf_AISTATUS) *NR_OBJS) 


7 
for( i = 0; i < NR_OBJS; it+ ) 
{ 


aiValuesRef[i][0] = &aiValue[i]; // Same order as in 
aiValuesRef[i][1] = &aiStatus[i];// “aiAttributes”. 
aiObjValues[i] = aiValuesRef [il]; 


} 
apiResult = bciGetAttributes (aiObjNames, 
NR_OBJS, 
aiAttributes, 
NR_ATTR, 
aiValueSizes, 
aiObjValues, 
aiObjStatus ); 
if (apiResult != bciSUCCESS) 
MessageBox( NULL, “API Status Error”, “Test”, MB_OK ); 
else 
MessageBox( NULL, “Successful”, “Test”, MB_OK ); 
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B.1.3.4 Get Attribute Values on Event 
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Introduction 


The purpose of this function is to subscribe for attribute values from object instances when a 
specific event is detected in the objects. This function can operate with initialize or without. 
The function creates a permanent subscription that persists until it is removed. A special 
function is included to remove subscriptions. 


Calling Name 
NAME: bciGetAttribOnEvent - subscribe for data on event (portable). 


NAME: wiuGetAttribOnEvent- subscribe for data on event (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciGetAttribOnEvent(const char** objectNames, 

int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status, 

int event, 

size_t eventSize, 

void* eventData, 

void (*eventFunction)(const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData)); 


Advalnform for Windows specific: 


BciStatus pascal wiuGetAttribOnEvent(const char* protNames, 
unsigned long int* objectRef, 
const char** objectNames, 
int objectCount, 
const int* attributes, 
int attributeCount, 
const size_t* valueSizes, 
void*** values, 
BciObjStatus* status, 
int event, 
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size_t eventSize, 
void* eventData, 
void (*eventFunction)(unsigned long int objectRef, 
const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData)); 


BciStatus pascal wiuMMI]GetAttribOnEvent(const char* protName, 


int* requestRef, 

unsigned long int* objectRef, 

const char** objectNames, 

int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status, 

int event, 

size_t eventSize, 

void* eventData, 

void (*eventFunction)(unsigned long int objectRef, 
const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData)); 


[in] specifies which protocol handler to use (wiu specific). 


[in] array with application-specific references to objects (wiu specific). 


[out]a handle to the subscription request, returned by User API (wiu specific). 


PARAMETERS 
protName 
objectRef 
requestRef 
objectNames [in] 
objectCount [in] 
attributes [in] 
attributeCount [in] 
valueSizes [in] 
values 
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array of names of object instances from which to get attribute values. 
number of object names in the objectNames array. 

array with attribute identifiers from which to get values. 

number of attribute identifiers in the attributes array. 


sizes of the areas where the attribute values are stored. 


[inout]array of pointers to array with pointers to data areas where the attribute 


values are stored. 
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status [out]array of status, one status per object. 

event [in] event identifier. 

eventSize [in] size of the data area where the event data is stored. 
eventData [in] pointer to the data area where the event data is stored. 


eventFunction [in] pointer to a ‘void pascal’ function that will be called when the data is 
received from one object instance. 


objectName [in] name of the object that has sent data. 
status [in] status of the object access. 
attributes [in] array with attribute identifiers. 


attributeCount{in] number of attribute identifiers in the attributes array and number of values 
in the values array. 


values [in] array with pointers to data areas where the attribute data is received. 
event [in] event identifier. 


eventData [in] pointer to a data area where the event data is received. 


DESCRIPTION 


The bciGetA ttribOnEvent function gets attribute values and eventData on event. On event 
means that when the object instance detects the event, data is sent to the caller and the 
eventFunction is called. The bciGetAttribOnEvent function sets up a permanent subscription 
on the event, so the eventFunction is called whenever the event is detected. To remove the 
subscription, call the bciCancelGet function. ! 


You can use the objectRef, retrieved from wiuObjectType, as a shortcut to access the objects 
without symbolic name translation. To enable the shortcut, set the objectName to a NULL 
pointer. If the objectName is used, the objectRef can be used by the application for pointer or 
reference to storage of your own application data. 


The attribute identifiers in the attributes array and the event identifier are obtained from an 
object type include file or the ...ObjTypeAttrs function. The object type include file is also used 
to get the data types of the attribute values and eventData. 


The bciGetA ttribOnEvent function verifies that the requested attributes and event are part of 
the object type to which the object instance belongs. In addition, it also verifies that the 
valueSizes and eventSize are correct. 


The function cannot verify that the correct data types are used for the attribute values and 
eventData. That is the caller’s responsibility. The eventFunction gets its arguments from the 
arguments to the bciGetAttribOnEvent function. This means that these arguments cannot be 
allocated on the stack. They must be allocated from the global heap. 


RETURN VALUE 


BciStatus giving status of the function call. 


1. It is essential that the subscription be removed before application terminates. 
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EXAMPLE 


The following example gets the status from one DI object on event: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 
#include <omf_DI.h> 


#define NR_OBJS 3 
#define NR_ATTR 1 
#define OBJNAMLEN 21 


HANDLE hinst; 
BCIEVENTPROC lpfnEventProc; 


int i; 

BciStatus apiResult; 

static char* diObjNames[NR_OBJS] = {™“DI1”",”"D1I2",”"D1I3"}; 

int didAttributes[NR_ATTR] = {OMF_DISTATUSID}; 

size_t diValueSizes[NR_ATTR] = {sizeof( Omf_DISTATUS ) }; 
void** diValues[NR_OBJS]; 

void* diValuesRef [NR_OBJS] [NR_ATTR]; 


BciObjStatus* diObjStatus;// Must be allocated globally 
Omf_DISTATUS* diStatus; // Must be allocated globally 


lpfnEventProc=(BCIEVENTPROC) MakeProcInstance((FARPROC)treatEven 
t, hiInst); 
diObjStatus = 
(BciObjStatus*) wiuMalloc (sizeof (BciObjStatus) *NR_OBJS) ; 
diStatus=(Omf_DISTATUS*) wiuMalloc (sizeof (Omf_DISTATUS) *NR_OBJS) 


, 
for( i = 0; i < NR_OBJS; it+ ) 
{ 
diValuesRef [i] [0] 
diValuesRef [i] [1] 
diValues [i] = 
} 
apiResult = bciGetAttribOnEvent (diObj Names, 
NR_OBJS, 
diAttributes, 
NR_ATTR, 
diValueSizes, 
diValues, 
diObjStatus, 
OMF_DIEVENTID, 
0, 
NULL, 
lpfnEventProc ); 


= &diValue[i];// Same order as for 
&édiStatus[i];// “diAttributes” 
diValuesRef [i]; 


if (apiStatus != bciSUCCESS) 
MessageBox( NULL, “API Status Error”, “Test”, MB_OK ); 
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else 


// 
// 


// 


MessageBox( NULL, “Successful”, “Test”, MB_OK ); 


Application callback function 


void pascal treatEventData( unsigned long int objectRef, 
const char* objectName, 
BciObjStatus objStatus, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData ) 

if (objStatus.codes == bciOBJ_SUCCESS) 


{ 
// Treat the updated data 


} 
else 


{ 
wsprintf( szString, "EVENT callback %s, Attribs=%d, 


Object status=%d flags=%d", 
objectName, attributeCount, 
objStatus.codes, objStatus.flags ); 


bciSendMessage( 1, 2, szAppName, 
FILE r LINE , bciINFORMATION, 


bciOPERATOR, 1, 2, szString ); 
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B.1.3.5 Get Attribute Values Cyclically 


Introduction 


The purpose of this function is to subscribe cyclically on attribute values from object instances. 
The function creates a permanent subscription which persists until it is removed. A special 
function is included to remove subscriptions. 


Calling Name 


NAME: bciGetAttribCyclic - subscribe for cyclic data (portable). 


NAME: wiuGetAttribCyclic - subscribe for cyclic data (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciGetA ttribCyclic(const char** objectNames, 


int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status 

int cycleTime, 

void (*cyclicFunction)(const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attribute Count, 
void** values)); 


Advalnform for Windows specific: 


BciStatus pascal wiuGetAttribCyclic(const char* protName, 
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unsigned long int* objectRef, 

const char** objectNames, 

int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status 

int cycleTime, 

void (*cyclicFunction)(unsigned long int objectRef, 
const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values)); 
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BciStatus pascal wiuMM]GetA ttribCyclic(const char* protName, 


PARAMETERS 


protName 
objectRef 


requestRef 


objectNames 


objectCount 
attributes 
attributeCount 
valueSizes 


values 


status 
cycleTime 


cyclicFunction 


objectName 
status 


attributes 


in| 


in| 


[ 
[ 
[ 
[ 


attributeCount [in] 


values 


[in] 


unsigned long int* objectRef, 

int®* requestRef, 

const char** objectNames, 

int objectCount, 

const int* attributes, 

int attributeCount, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status 

int cycleTime, 

void (*cyclicFunction)(unsigned long int objectRef, 
const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attribute Count, 
void** values)); 


specifies which protocol handler to use (wiu specific). 
array with application-specific references to objects (wiu specific). 


a handle to the subscription request, returned by User API (wiu 
specific). 


array of names of the object instances from which to get attribute 
values. 


number of object names in the objectNames array. 

array with attribute identifiers from which to get values. 
number of attribute identifiers in the attributes array. 
sizes of the areas where the attribute values are stored. 


array of pointers with pointers to data areas where the attribute 
values are stored. 


array of status, one status per object. 
time in seconds between each time attribute values are gotten. 


pointer to function ‘void pascal’ that will be called when the data is 
received from an object instance. 


name of the object that has sent data. 
status of the object access. 
array with attribute identifiers. 


number of attribute identifiers in the attributes array and number of 
values in the values array. 


array with pointers to data areas where the attribute data is received. 
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DESCRIPTION 


The bciGetAttribCyclic function gets attribute values cyclically. The beiGetAttribCyclic 
function sets up a permanent subscription with the specified cycleTime, so the cyclicFunction is 
called whenever a cycle ends. To remove the subscription, call the beiCancelGet function!. 


You can use the objectRef, retrieved from wiuObjectType, as a shortcut to access the objects 
without symbolic name translation. To enable the shortcut, set the objectName to a NULL 
pointer. If the objectName is used, the objectRef can be used by the application for pointer or 
reference to storage of your own application data. 


The attribute identifiers in the attributes array are obtained from an object type include file or 
the ..ObjTypeAttrs function. The object type include file is also used to get the data types of the 
attribute values. The beiGetAttribCyclic function verifies that the requested attributes are part 
of the object type the object instances belong to and that the valueSizes are correct. The function 
cannot verify that the correct data types are used for the attribute values. That is the caller’s 
responsibility. 


The cycleTime parameter is rounded off to the nearest of 1, 3 or 9 seconds when subscribing 
from a Master* node. The cyclicFunction gets its arguments from the arguments to the 
bciGetA ttribCyclic function. This means that these arguments cannot be allocated on the stack. 
They must be allocated from the global heap. 


RETURN VALUE 


BciStatus giving status of the function call. 


EXAMPLE 


The following example cyclically gets the value and status from one AI object: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 
#include <omf_AI.h> 


#define NR_OBJS 3 
#define NR_ATTR 2 
#define OBJNAMLEN 21 


HANDLE hinst; 
BCICYCLICPROC lpfnCyclicProc; 


1. It is essential that the subscription be removed before application terminates. 
2. Master node is either a MasterPiece or SuperView node. 
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int i; 

int aiCycleTime = 10; 

BciStatus apiResult; 

static char* aiObjNames[NR_OBJS] = {‘AI1”,”AI2",”AI3"}; 

int aiAttributes[NR_ATTR] = {OMF_AIVALUEID, 

OMF_AISTATUSID}; 

size_t aiValueSizes[NR_ATTR] = {sizeof( Omf_AIVALUE ), 
sizeof( Omf_AISTATUS )}; 

void** aiValues [NR_OBJS]; 

void* aiValuesRef [NR_OBJS] [NR_ATTR]; 

BciObjStatus* aiObjStatus;// Must be allocated globally 

Omf_AIVALUE* aiValue; // Must be allocated globally 

Omf_AISTATUS* aiStatus; // Must be allocated globally 


lpfnCyclicProc=(BCICYCLICPROC) MakeProcInstance ((FARPROC) treatCy 
clic, hInst); 
aiObjStatus=(BciObjStatus*) wiuMalloc (sizeof (BciObjStatus) *NR_OB 
JS); 

aiValue=(Omf_AIVALUE*) wiuMalloc( sizeof (Omf_AIVALUE) *NR_OBJS) ; 
aiStatus=(Omf_AISTATUS*) wiuMalloc (sizeof (Omf_AISTATUS) *NR_OBJS) 


, 

for( i = 0; i < NR_OBJS; it+ ) 
{ 
aiValuesRef [i] [0] 
aiValuesRef [i] [1] 
aiValues[i] = 
} 

apiResult = bciGetAttribCyclic( aiObjNames, 

NR_OBJS, 

aiAttributes, 

NR_ATTR, 

aiValueSizes, 

aiValues, 


&aiValue[i];// Same order as for 
éaiStatus[i];// “aiAttributes” 
aiValuesRef [i]; 


aiObjStatus, 
aiCycleTime, 
lpfnCyclicProc ); 
if (apiStatus != bciSUCCESS) 
MessageBox( NULL, “API Status Error”, “Test”, MB_OK ); 
else 


MessageBox( NULL, “Successful”, “Test”, MB_OK ); 


// 

// Application callback function 

// 

void pascal treatCyclicData( unsigned long int objectRef, 
const char* objectName, 
BciObjStatus objStatus, 
const int* attributes, 
Int attributeCount, 
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void** values ) 
{ 
if (objStatus.codes == bciOBJ_SUCCESS) 
{ 
// Treat the updated data 
} 
else 
{ 
wsprintf( szString, "CYCLIC callback %s, Attribs=%d, 
Object status=%d flags=%d", 
objectName, attributeCount, 
objStatus.codes, objStatus.flags ); 
bciSendMessage( 1, 2, szAppName, 
FILE ; LINE__, bciINFORMATION, 
bciOPERATOR, 1, 2, szString ); 
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B.1.3.6 Get Attribute Values on Event with Init 
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Introduction 


This function reads attribute values and event data on event with initialize operation and persists 
until removed. Use this function only for historical data access through the object 
“LOG_MANAGER”. 


Calling Name 


NAME: bciGetAttribOnEventWithInit - subscribe for data on event with init operation 
(portable). 


NAME: wiuGetAttribOnEventWithInit - subscribe for data on event with init operation 
(not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciGetAttribOnEventWithInit(const char** objectName, 

int objectCount, 

const int* attributes, 

int attribute Count, 

const size_t* valueSizes, 

void*** values, 

BciObjStatus* status 

int event, 

size_t eventSize, 

void* eventData, 

void (*eventFunction)(const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData), 

int operation, 

size_t argSize, 

void** arguments); 


Advalnform for Windows specific: 


BciStatus pascal wiuGetAttribOnEventWithInit(const char* protName, 
unsigned long int* objectRef, 
const char** objectName, 
int objectCount, 
const int* attributes, 
int attributeCount, 
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PARAMETERS 
protName 


objectRef 


objectName 


objectCount 
attributes 
attributeCount 
valueSizes 


values 


status 
event 
eventSize 
eventData 


eventFunction 


objectRef 
objectName 


Status 


[in] 
[in] 


[in] 


[in] 
[in] 
[in] 
[in] 


[inout] 


[out] 
[in] 
[in] 
[in] 
[in] 


[in] 


[in] 


const size_t* valueSizes, 

void*** values, 

BciObjStatus* status 

int event, 

size_t eventSize, 

void* eventData, 

void (*eventFunction)( 
unsigned long int objectRef, 
const char* objectName, 
BciObjStatus status, 
const int* attributes, 
int attributeCount, 
void** values, 
int event, 
void* eventData), 

int operation, 

size_t argSize, 

void** arguments); 


specifies which protocol handler to use (wiu specific). 


array with application-specific references to objects 
(wiu specific). 


array of names of the object instances from which to get 
attribute values. 


number of object names in the objectNames array. 

array with attribute identifiers from which to get values. 
number of attribute identifiers in the attributes array. 
sizes of the areas where the attribute values are stored. 


array of pointers to array with pointers to data areas where the 
attribute values are stored. 


array of status, one status per object. 

event identifier. 

size of the data area where the event data is stored. 
pointer to the data area where the event data is stored. 


pointer to function that is called when the data is received from 
the object instance. 


(wiu specific). 
name of the object that has sent data. 


status of the object access. 
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attributes [in] array with attribute identifiers. 


attributeCount [in] number of attribute identifiers in the attributes array and 
number of values in the values array. 


values [in] array with pointers to data areas where the attribute data is 
received. 

event [in] event identifier. 

eventData [in] pointer to a data area where the event data is received. 
operation [in] operation identifier. 
arg Size [in] size of the argument data. 
arguments [inout] array of pointers to the area where argument data is stored. 
DESCRIPTION 


The bciGetA ttribOnEventWithInit function does the same thing as the 
bciGetAttribOnEvent function (see description of beiGetAttribOnEvent function), but adds 
an initialization operation. The initialization operation enables the caller to send information to 
the object instance about how to get the attribute values. The attribute identifiers in the attributes 
array and the operation identifier are obtained from an object type include file. The object type 
include file is also used to get the data types of the attribute values and operation argument. 
For further information, refer to bciExecOperation. 


The bciGetA ttribOnEventWithInit function verifies that the requested attributes and the 
operation are part of the object type to which the object instances belong and that the valueSizes 
and argSize are correct. The function cannot verify that the correct data types are used for the 
attribute values and argument data. That is the caller’s responsibility. 


RETURN VALUE 


BciStatus giving status of the function call. 


EXAMPLE 
Not available for AF 100. 
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B.1.3.7 Cancel Get 


Introduction 


The purpose of this function is to remove subscriptions created with the functions described in 
Get Attribute Values on Event and Get Attribute Values Cyclically. 


Calling Name 
NAME: bciCancelGet - cancel a number of subscriptions (portable). 
NAME: wiuCancelGet - cancel a number of subscriptions (not portable). 


NAME: wiuMICancelGet - cancel a number of subscriptions (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciCancelGet(const char** objectNames, 
int objectCount); 


Advalnform for Windows specific: 


BciStatus pascal wiuCancelGet(const char** protName, 
unsigned long int objectRef, 
const char** objectNames, 
int objectCount); 


BciStatus pascal wiuMMICancelGet(const char** protName, 
unsigned long int objectRef, 
int requestRef, 
const char** objectNames, 
int objectCount); 


PARAMETERS 
protName [in] specifies which protocol handler to use (wiu specific). 
objectRef [in] array with application-specific references to objects 
(wiu specific). 
requestRef [in] request handle retrieved through the subscription request 
(wiu specific). 
objectNames [in] array of names of the object instances for which to cancel 


subscription. 


objectCount [in] number of object names in the objectNames array. 
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DESCRIPTION 


The bciCancelGet function removes all previously requested permanent subscriptions from a 
number of object instances. Permanent subscriptions are set up with the bciGetAttribOnEvent, 
bciGetAttribCyclic, bciGetAttribOnEventWithInit and the bciGetAttribCyclicWithInit 
functions 


RETURN VALUE 


BciStatus giving status of the function call. 


EXAMPLE 


The following example cancels subscriptions from the TEST_DI1 object: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus result; 
result = bciCancelGet( “TEST_DI1”, 1 ); 
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B.1.3.8 Cancel All Subscriptions 


Introduction 


This function removes all subscriptions towards all object instances the program/task has 
initiated. 


Calling Name 


NAME: bciCancelAll - cancel all subscriptions (portable). 


NAME: wiuCancelAll - cancel all subscriptions (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciCancelAll(void); 


Advalnform for Windows specific: 


BciStatus pascal wiuCancelAll(const char* protName); 


PARAMETERS 


protName [in] specifies which protocol handler to use (wiu specific). 


DESCRIPTION 


The bciCancelAll function removes all previously requested permanent subscriptions. 
Permanent subscriptions are set up with the bciGetAttribOnEvent, bciGetAttribCyclic, 
bceiGetAttribOnEventWithInit and the bciGetAttribCyclicWithInit functions. 


RETURN VALUE 


BciStatus giving status of the function call. 


EXAMPLE 


The following example cancels all subscriptions: 
#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus result; 
result = bciCancelAll(); 
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B.1.3.9 Execute Operation 


Calling Name 
NAME: bciExecOperation - execute an operation on one object (portable). 


NAME: wiuExecOperation - execute an operation on one object (not portable). 


SYNOPSIS 


#include <bciUAPI.h> 
#include <wiuOAS.h> 


BciStatus pascal bciExecOperation( const char* objectName, 
int operation, 
size_t argSize, 
void* arguments, 
BciObjStatus* status); 


Advalnform for Windows specific: 


BciStatus pascal wiuExecOperation( const char* protName, 
unsigned long int objectRef, 
const char* objectName, 
int operation, 
size_t argSize, 
void* arguments, 
BciObjStatus* status); 


PARAMETERS 

protName [in] specifies which protocol handler to use (wiu specific). 
objectRef [in] application-specific reference to object (wiu specific). 
objectName [in] name of the object instance on which to execute the operation. 
operation [in] operation identifier. 

arg Size [in] size of the argument data. 

arguments [inout] argument data. 

status [out] status for the object access. 

DESCRIPTION 


The bciExecOperation function executes one operation on an object instance. The object 
include file is used to get the operation identifier. The object type include file is also used to get 
the data type for the argument data. 
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The beiExecOperation function verifies that the operation identifier is part of the object type to 
which the object instance belongs and that the argument size is correct. The function cannot 
verify that the correct data types are used for the argument data. That is the caller’s 
responsibility. For further information about operations and their corresponding arguments, 
refer to the Advalnform Object Types Reference Manual. 


RETURN VALUE 


BciStatus giving status of the function call. 


EXAMPLE 


The following example executes the order operation (to set the value to 10.0) in an AI object 
with the name “TEST_AI”: 

#include <bciUAPI.h> 

#include <wiuOAS.h> 

#include <omf_AI.h> 

#include <dccodes.h> 


BciStatus result; 
BciObjStatus objStatus; 
Omf_ATORDER order; 


order.opCode = dcVALUE_CHANGE_DCX; 
order.opProp dcACT_VALUE_DCX; 
order.typeOfReq = dcPROG; 


order.eventLog = 0; 
order.dialogld = 0; 
order.aValue = 10.0 


result = bciExecOperation( “TEST_AI”, OMF_AIORDERID, 
sizeof(order), &order, 


é&éo0b Status ); 
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